Google Cloud Firestore 擴充功能

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

版本:1.4.1

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

本文提供設定和使用這個擴充功能的參考資料。從 API Proxy 使用這個擴充功能前,您必須:

  1. 在儲存資料的 Firebase 主控台中建立 Firebase 專案。

  2. 為服務帳戶產生金鑰

  3. 透過設定參考資料新增及設定擴充功能時,使用產生的金鑰 JSON 檔案內容。

關於 Cloud Firestore

Cloud Firestore 會將資料儲存在文件中,並以文件形式儲存。Cloud Firestore 會在您首次將資料新增至文件時,以隱含方式建立集合和文件。您不需要明確建立集合或文件。

如要進一步瞭解 Cloud Firestore 的一般資訊,請參閱 Cloud Firestore 說明文件中的開始使用 Firestore

範例

以下範例說明如何使用擴充功能呼叫政策,為 Cloud Firestore 擴充功能動作設定支援。

新增資料

下列擴充功能摘要政策會將名為 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>

取得資料

在這個範例中,Extension callout 政策會從 users 集合擷取 freewill@example.com 文件的值。在這裡,<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>

刪除資料

在這個範例中,Extension callout 政策會從 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>

查詢資料

在這個範例中,ExtensionSummary 政策會查詢 cities 集合。查詢結果會按 statepopulation 欄位篩選。在這裡,<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

刪除珍藏內容中的單一文件。

要求參數

<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 運算子連接的多個條件。

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

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

以下範例指定兩個條件陣列,根據集合的 statepopulation 欄位進行篩選:

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

在執行階段,這個動作會解讀為查詢,如下所示:

選取州/省為「CA」且人口小於 100,000 的所有城市

含有多個條件的查詢必須在 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」且人口小於 100,000 的所有城市

參數 說明 類型 預設 需要
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 這項擴充功能應使用 whem 提出要求的 Cloud Firestore 資料庫網址。這個網址通常會用於 https://DATABASE_NAME.firebaseio.com 形式。 無。 可以。
憑證 在 Apigee Edge 控制台中輸入時,您會看到使用 Firebase 操作說明產生的金鑰檔案內容。透過管理 API 傳送時,是從金鑰檔案產生的 Base64 編碼值, 無。 可以。