本頁面由 Cloud Translation API 翻譯而成。

Google Cloud Firestore 擴充功能

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

版本：2.0.0

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

本內容提供設定和使用此擴充功能的參考資訊。在透過 API 代理程式使用這個擴充功能前，您必須：

在儲存資料的 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 代理程式中使用，請使用下列說明。如要瞭解如何使用 Apigee 控制台設定擴充功能，請參閱「新增及設定擴充功能」。

常見的擴充功能屬性

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

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

這個擴充功能套件的屬性

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