Google Cloud Firestore 拡張機能

バージョン: 1.2.0

Cloud Firestore データベースのデータの作成、読み取り、削除を行います。

ここでは、この拡張機能を構成して使用する場合のリファレンスを提供します。API プロキシからこの拡張機能を使用する前に、次の操作を行う必要があります。

  1. データが保存されている Firebase コンソールで Firebase プロジェクトを作成します。

  2. サービス アカウントキーを生成します。

  3. 拡張機能の追加と構成を行うときに、構成リファレンスを使用して、生成されたキーの JSON ファイルのコンテンツを使用します。

Cloud Firestore について

Cloud Firestore はデータをドキュメントに保存します。ドキュメントはコレクションに保存されます。ドキュメントに初めてデータを追加するときに、Cloud Firestore はコレクションとドキュメントを自動的に作成します。コレクションやドキュメントを明示的に作成する必要はありません。

Cloud Firestore の概要については、Cloud Firestore ドキュメントの Firestore スタートガイドをご覧ください。

例

次の例は、ExtensionCallout ポリシーを使用して Cloud Firestore 拡張機能アクションのサポートを構成する方法を示しています。

データの追加

次の ExtensionCallout ポリシーは、freewill@example.com というドキュメントを users コレクションに追加します。data プロパティは、新しいドキュメントのフィールドと値を指定します。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Add-User-Data">
    <DisplayName>Add User Data</DisplayName>
    <Connector>my-cloud-firestore-extension</Connector>
    <Action>setDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "freewill@example.com",
        "data" : {
            "firstName": "Will",
            "lastName": "Witman",
            "address": "270-8243 Tempor St.",
            "city": "Fort Worth",
            "region": "TX",
            "postalCode": "86519",
            "email": "freewill@example.com",
            "username": "freewill444"
        }
    }]]></Input>
</ConnectorCallout>

データの取得

次の例では、ExtensionCallout ポリシーにより、users コレクションから freewill@example.com ドキュメントの値を取得します。ここでは、<Output> 要素の parsed 属性が false に設定されているため、返される結果はオブジェクトにパースされた JSON ではなく、文字列としての JSON になります。詳細については、<Output> 要素リファレンスをご覧ください。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Get-User-Data">
    <DisplayName>Get User Data</DisplayName>
    <Connector>straut-cloud-firestore-extension</Connector>
    <Action>getDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "freewill@example.com"
    }]]></Input>
    <Output parsed="false">firestore.userdata.retrieved</Output>
</ConnectorCallout>

次の Assign Message ポリシーは、拡張機能のレスポンスを格納する変数の値を使用して、レスポンス ペイロードを割り当てます。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage name="CopyUserDataToResponse">
    <DisplayName>Copy User Data To Response</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{firestore.userdata.retrieved}</Payload>
    </Set>
</AssignMessage>

データの削除

次の例では、ExtensionCallout ポリシーにより、users コレクションから lizzie@example.com ドキュメントを削除します。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Delete-User-Data">
    <DisplayName>Delete User Data</DisplayName>
    <Connector>my-cloud-firestore-extension</Connector>
    <Action>deleteDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "lizzie@example.com"
    }]]></Input>
</ConnectorCallout>

クエリでデータを取得

この例では、ExtensionCallout ポリシーがクエリで cities コレクションを取得しています。クエリ結果は state フィールドと population フィールドでフィルタリングされます。ここでは、<Output> 要素の parsed 属性が false に設定されているため、返される結果はオブジェクトにパースされた JSON ではなく、文字列としての JSON になります。詳細については、<Output> 要素リファレンスをご覧ください。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Query-City-Data">
    <DisplayName>Query City Data</DisplayName>
    <Connector>cloud-firestore-extension</Connector>
    <Action>query</Action>
    <Input><![CDATA[{
        "colName":"cities",
        "queryArray":[
          ["state", "==", "CA"],
          ["population","<",1000000]
        ]
    }]]></Input>
    <Output parsed="false">compound-query-output</Output>
</ConnectorCallout>

次の Assign Message ポリシーは、拡張機能のレスポンスを格納する変数の値を使用して、レスポンス ペイロードを割り当てます。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage name="CopyQueryResultsToResponse">
    <DisplayName>Copy Query Results To Response</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{firestore.querydata.retrieved}</Payload>
    </Set>
</AssignMessage>

アクション

deleteDocument

コレクションから 1 つのドキュメントを削除します。

リクエスト パラメータ

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>
パラメータ 説明 型 デフォルト 必須
colName 削除するドキュメントを含むコレクションの名前 文字列 なし ○
docName 削除するドキュメントの名前 文字列 なし ○

レスポンス

なし

getDocument

1 つのドキュメントのコンテンツを取得します。

リクエスト パラメータ

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>
パラメータ 説明 型 デフォルト 必須
colName 取得するドキュメントを含むコレクションの名前 文字列 なし ○
docName 取得するドキュメントの名前 文字列 なし ○

レスポンス

ドキュメントのコンテンツを含む JSON 形式のオブジェクト

query

フィルタを構成する条件を指定し、コレクションをクエリで取得しています。

このアクションの queryArray パラメータは、配列の配列（フィルタリング条件がない場合は空の配列）を指定します。内部配列には、フィルタの条件が指定されます。複数の内部配列は、AND 演算子で結合された複数の条件を表します。

内部条件の各要素は、条件の一部を表しています。条件配列は常に次の 3 つの要素から構成されます。

  • コレクションのフィールドを指定する左側の要素
  • 演算子を表す中間の要素
  • コレクション フィールド値を指定する右側の要素

次の例では、コレクションの state フィールドと population フィールドに基づいてフィルタリングする 2 つの条件配列を指定しています。

<Input><![CDATA[{
  "colName":"cities",
  "queryArray":[
    ["state", "==", "CA"],
    ["population","<",1000000]
  ]
}]]></Input>

このアクションは、ランタイムに次のようなクエリとして解釈されます。

state = 'CA' で population < 1000000 の条件満たすすべての都市を選択します。

複数の条件を含むクエリは、Cloud Firestore で複合インデックスによってサポートされる必要があります。詳細については、Cloud Firestore のインデックス タイプをご覧ください。

リクエスト パラメータ

構文

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "queryArray" : "queryArray": query-condition-array
}]]></Input>

例

この例では、queryArray パラメータは colName パラメータで指定された cities コレクションをフィルタする 2 つの条件を指定します。

複数の条件を含むクエリは、Cloud Firestore で複合インデックスによってサポートされる必要があります。詳細については、Cloud Firestore のインデックス タイプをご覧ください。

<Input><![CDATA[{
  "colName":"cities",
  "queryArray":[["state", "==", "CA"],["population","<",1000000]]
}]]></Input>

このアクションは、ランタイムに次のようなクエリとして解釈されます。

state = 'CA' で population < 1000000 の条件満たすすべての都市を選択します。

パラメータ 説明 型 デフォルト 必須
colName クエリで取得するコレクションの名前 文字列 なし ○
queryArray フィルターの一部を指定する条件配列の配列。条件を省略するには、空の配列を指定します（結果はフィルタリングされません）。 Array なし ○

レスポンス

ドキュメントのコンテンツを含む JSON 形式のオブジェクト

setDocument

ドキュメントを Cloud Firestore コレクションにコピーします。ドキュメントがコレクションにすでに存在する場合、ドキュメントは上書きされます。

リクエスト パラメータ

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name",
  "data" : "data-to-copy"
}]]></Input>
パラメータ 説明 型 デフォルト 必須
colName ドキュメントを作成するコレクションの名前 文字列 なし ○
docName data のコピー先となるドキュメントの名前。 文字列 なし ○
data docName にコピーするデータ。有効な JSON オブジェクトにする必要があります。配列はサポートされていません。 Object なし ×

レスポンス

なし

構成リファレンス

この拡張機能を API プロキシで使用するように構成してデプロイする場合は、以下のプロパティを使用します。Apigee Console で拡張機能を構成する手順については、拡張機能の追加と構成をご覧ください。

拡張機能の共通プロパティ

すべての拡張機能には次のプロパティがあります。

プロパティ 説明 デフォルト 必須
name この拡張機能に付ける名前。 なし ○
packageName Apigee Edge から提供された拡張機能パッケージの名前。 なし ○
version 拡張機能を構成する拡張機能パッケージのバージョン番号。 なし ○
configuration 追加する拡張機能に固有の構成値。この拡張機能パッケージのプロパティをご覧ください。 なし ○

この拡張機能パッケージに固有のプロパティ

プロパティ 説明 デフォルト 必須
firestoreDB この拡張機能がリクエスト発生時に使用する Cloud Firestore データベースの URL。通常、この URL は https://DATABASE_NAME.firebaseio.com という形式です。 なし ○
credentials Apigee Edge コンソールに入力する場合は、Firebase の手順に沿って作成したキーファイルの内容です。Management API で設定する場合は、キーファイルから生成された base64 エンコード値になります。 なし ○