Google Cloud Firestore 擴充功能

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

版本：2.0.2

在 Cloud Firestore 資料庫中建立、讀取或刪除資料。

這項內容提供設定及使用這項擴充功能的參考資料。如要透過 API Proxy 使用這項擴充功能，請務必先完成下列步驟：

在 Firebase 控制台中建立 Firebase 專案，用於儲存資料。
產生服務帳戶金鑰。
使用產生的金鑰 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>

下列「指派訊息」政策會使用儲存擴充功能回應的變數值，指派回應酬載。

<?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>

下列「指派訊息」政策會使用儲存擴充功能回應的變數值，指派回應酬載。

<?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

從集合中刪除單一文件。

要求參數

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>

參數	說明	類型	預設	必填
colName	包含要刪除文件的集合名稱。	字串	無。	是。
docName	要刪除的文件名稱。	字串	無。	是。

回應

無。

getDocument

擷取單一文件的內容。

要求參數

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>

參數	說明	類型	預設	必填
colName	要從中擷取文件的集合名稱。	字串	無。	是。
docName	要擷取的文件名稱。	字串	無。	是。

回應

物件，內含 JSON 格式的文件內容。

查詢

指定構成篩選器的條件，查詢集合。

這項動作的 queryArray 參數會指定陣列的陣列 (或不含篩選條件的空陣列)。每個內部陣列都會指定篩選器的條件。多個內部陣列代表以 AND 運算子連結的多個條件。

內部條件陣列中的每個元素都代表條件的一部分。條件陣列一律包含下列三個元素：

指定集合欄位的左側元素。
指定運算子的中間元素。
指定集合欄位值的右側元素。

以下範例指定兩個條件陣列，根據集合的 state 和 population 欄位進行篩選：

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

在執行階段，這項動作會解讀為查詢，例如：

選取所有州別為「CA」且人口數小於 1000000 的城市

如果查詢包含多個條件，Cloud Firestore 必須透過複合式索引支援這類查詢。詳情請參閱「Cloud Firestore 中的索引類型」。

要求參數

語法

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

範例

在本範例中，queryArray 參數會指定兩個條件，用來篩選 colName 參數指定的 cities 集合。

如果查詢包含多項條件，Cloud Firestore 必須透過複合式索引支援這項查詢。詳情請參閱「Cloud Firestore 中的索引類型」。

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

在執行階段，這項動作會解讀為查詢，例如：

選取所有州別為「CA」且人口數小於 1000000 的城市

參數	說明	類型	預設	必填
colName	要查詢的集合名稱。	字串	無。	是。
queryArray	條件陣列的陣列，共同指定篩選器的各個部分。指定空陣列可省略條件 (不篩選結果)。	陣列	無。	是。

回應

物件，內含 JSON 格式的文件內容。

setDocument

將文件複製到 Cloud Firestore 集合。如果該文件已存在於集合中，系統會覆寫該文件。

要求參數

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name",
  "data" : "data-to-copy"
}]]></Input>

參數	說明	類型	預設	必填
colName	要在其中建立文件的集合名稱。	字串	無。	是。
docName	要複製 `data` 的文件名稱。	字串	無。	是。
資料	要複製到「`docName`」的資料。這必須是有效的 JSON 物件。不支援陣列。	物件	無。	不會。

回應

無。

設定參考資料

設定及部署這個擴充功能，以便在 API Proxy 中使用時，請參考下列資訊。如要瞭解如何使用 Apigee 控制台設定擴充功能，請參閱「新增及設定擴充功能」。

常見的擴充功能屬性

每個擴充功能都有下列屬性。

屬性	說明	預設	必要
`name`	您要為這項擴充功能設定的名稱。	無	相容
`packageName`	Apigee Edge 指定的擴充功能套件名稱。	無	相容
`version`	擴充功能的擴充功能套件版本號碼。	無	相容
`configuration`	您要新增的擴充功能專屬的設定值。請參閱「這個擴充功能套件的屬性」一文	無	相容

這個擴充套件的屬性

屬性	說明	預設	必填
firestoreDB	這項擴充功能在提出要求時應使用的 Cloud Firestore 資料庫網址。這個網址通常會採用 `https://DATABASE_NAME.firebaseio.com` 的形式。	無。	是。
憑證	在 Apigee Edge 控制台中輸入時，這是您使用 Firebase 指示產生的金鑰檔案內容。透過管理 API 傳送時，這是從金鑰檔案產生的 base64 編碼值。	無。	是。