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 ポリシーが、freewill@example.com ドキュメントの値を users コレクションから取得しています。ここで、<Output> 要素の parsed 属性が false に設定されているため、結果の 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 がオブジェクトとして解析されず、文字列として返されます。詳細については、<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 削除するドキュメントを含むコレクションの名前 String なし
docName 削除するドキュメントの名前 String なし

レスポンス

なし

getDocument

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

リクエスト パラメータ

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

レスポンス

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

query

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

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

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

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

次の例では、2 つの条件配列を指定して、条件の statepopulation フィールドに基づいてフィルタリングを行っています。

<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 パラメータに 2 つの条件を指定しています。これにより、colName パラメータで指定した cities 条件のフィルタリングを行います。

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

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

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

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

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

レスポンス

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

setDocument

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

リクエスト パラメータ

<Input><![CDATA[{
      "colName" : "firestore-collection-name",
      "docName" : "firestore-document-name",
      "data" : "data-to-copy"
    }]]></Input>
    
パラメータ 説明 デフォルト 必須
colName ドキュメントを作成するコレクションの名前 String なし
docName data をコピーするドキュメントの名前 String なし
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 エンコード値になります。 なし