Google Cloud Firestore 扩展程序

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

版本:1.4.1

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

下面的分配消息政策使用存储扩展程序响应的变量的值来分配响应载荷。

<?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 集合。查询结果按 statepopulation 字段进行过滤。在这里,<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>

Action

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 运算符连接的多个条件。

内部条件数组中的每个元素都表示该条件的一部分。条件数组始终包含以下 3 个元素:

  • 指定集合字段的左侧元素。
  • 指定运算符的中间元素。
  • 用于指定集合字段值的右侧元素。

以下示例指定了要根据集合的 statepopulation 字段进行过滤的两个条件数组:

<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 复制到的文档的名称。 字符串 无。 有。
data 要复制到 docName 的数据。此字段必须是有效的 JSON 对象。不支持数组。 对象 无。 没有。

响应

无。

配置参考文档

在配置和部署此扩展程序以在 API 代理中使用时,请使用以下代码。如需了解使用 Apigee 控制台配置扩展程序的步骤,请参阅添加和配置扩展程序

通用扩展属性

每个扩展程序都有以下属性。

属性 说明 默认 必需
name 您为扩展程序配置此名称。
packageName Apigee Edge 提供的扩展包的名称。
version 配置扩展程序所用的扩展程序软件包的版本号。
configuration 特定于您要添加的附加信息的配置值。请参阅此扩展程序软件包的属性

此扩展程序软件包的属性

媒体资源 说明 默认 必需
firestoreDB 指向此扩展程序应使用的 Cloud Firestore 数据库的网址。此网址通常采用 https://DATABASE_NAME.firebaseio.com 格式。 无。 有。
凭据 在 Apigee Edge 控制台中输入时,这是您根据 Firebase 说明生成的密钥文件的内容。通过 Management API 发送时,它是从密钥文件生成的 base64 编码值。 无。 有。