此页面由 Cloud Translation API 翻译。

Google Cloud Firestore 扩展程序

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。信息

版本：2.0.0

在 Cloud Firestore 数据库中创建、读取或删除数据。

本文档提供了有关配置和使用此扩展程序的参考信息。在通过 API 代理使用此扩展程序之前，您必须满足以下条件：

在 Firebase 控制台中创建一个 Firebase 项目，用于存储您的数据。
为服务账号生成密钥。
使用配置参考添加和配置扩展程序时，请使用生成的密钥 JSON 文件的内容。

Cloud Firestore 简介

Cloud Firestore 将数据存储在文档中，而文档存储在集合中。在您首次向文档添加数据时，Cloud Firestore 就会隐式创建集合和文档。您不需要显式创建集合或文档。

如需详细了解 Cloud Firestore 的一般信息，请参阅 Cloud Firestore 文档中的 Firestore 使用入门。

示例

以下示例展示了如何使用 ExtensionCallout 政策配置对 Cloud Firestore 扩展程序操作的支持。

添加数据

以下 ExtensionCallout 政策会向 users 集合添加名为 freewill@example.com 的文档。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>

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

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

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

<?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 编码值。	无。	是。