解析程序的 Cosmos DB 数据源

2025-05-23

cosmosdb-data-source 解析程序策略使用 Cosmos DB 数据源解析 GraphQL 架构中对象类型和字段的数据。该架构必须作为 GraphQL API 导入到 API 管理。

使用策略配置单个查询请求、读取请求、删除请求或写入请求以及来自 Cosmos DB 数据源的可选响应。

注意

此策略为预览版。目前，API 管理的消耗层不支持该策略。

注意

按照策略声明中提供的顺序设置策略的元素和子元素。详细了解如何设置或编辑 API 管理策略。

策略语句

<cosmosdb-data-source> 
    <!-- Required information that specifies connection to Cosmos DB -->
    <connection-info> 
        <connection-string use-managed-identity="true | false"> 
            AccountEndpoint=...;[AccountKey=...;]
        </connection-string> 
        <database-name>Cosmos DB database name</database-name> 
        <container-name>Name of container in Cosmos DB database</container-name>     
    </connection-info>

    <!-- Settings to query using a SQL statement and optional query parameters -->
    <query-request enable-low-precision-order-by="true | false"> 
        <sql-statement> 
            SQL statement 
        </sql-statement> 
        <parameters> 
            <parameter name="Query parameter name in @ notation"> 
                "Query parameter value or expression"
            </parameter>
            <!-- if there are multiple parameters, then add additional parameter elements --> 
        </parameters> 
        <partition-key data-type="string | number | bool | none | null" template="liquid" > 
            "Container partition key" 
        </partition-key> 
        <paging> 
            <max-item-count template="liquid" > 
                Maximum number of items returned by query
            </max-item-count> 
            <continuation-token template="liquid"> 
                Continuation token for paging 
            </continuation-token> 
        </paging>
    </query-request>
    
    <!-- Settings to read item by item ID and optional partition key --> 
    <read-request> 
        <id template="liquid" >
            "Item ID in container"
        </id> 
        <partition-key data-type="string | number | bool | none | null" template="liquid" > 
            "Container partition key" 
        </partition-key>  
    </read-request> 
    
    <!-- Settings to delete item by ID and optional partition key --> 
    <delete-request consistency-level="bounded-staleness | consistent-prefix | eventual | session | strong" pre-trigger="myPreTrigger" post-trigger="myPostTrigger">
        <etag type="entity tag type" template="liquid" > 
            "System-generated entity tag" 
        </etag> 
        <id template="liquid">
            "Item ID in container"
        </id> 
        <partition-key data-type="string | number | bool | none | null" template="liquid"> 
            "Container partition key" 
        </partition-key> 
    </delete-request> 
    
    <!-- Settings to write item -->
    <write-request type="insert | replace | upsert" consistency-level="bounded-staleness | consistent-prefix | eventual | session | strong" pre-trigger="myPreTrigger" post-trigger="myPostTrigger">
        <id template="liquid">
            "Item ID in container"
        </id>
         <partition-key data-type="string | number | bool | none | null" template="liquid"> 
            "Container partition key"
        </partition-key>      
        <etag type="match | no-match" template="liquid" > 
            "System-generated entity tag" 
        </etag>
        <set-body template="liquid" >...set-body policy configuration...</set-body> 
    </write-request>
    
    <response> 
        <set-body>...set-body policy configuration...</set-body> 
        <publish-event>...publish-event policy configuration...</publish-event>
    </response>
    
</cosmosdb-data-source>

元素

名称	说明	必需
connection-info	指定与 Cosmos DB 数据库中的容器的连接。	是
query-request	指定对 Cosmos DB 容器的查询请求的设置。	配置 `query-request`、`read-request`、`delete-request` 或 `write-request` 其中之一
read-request	指定对 Cosmos DB 容器的读取请求的设置。	配置 `query-request`、`read-request`、`delete-request` 或 `write-request` 其中之一
delete-request	指定对 Cosmos DB 容器的删除请求的设置。	配置 `query-request`、`read-request`、`delete-request` 或 `write-request` 其中之一
write-request	指定对 Cosmos DB 容器的写入请求的设置。	配置 `query-request`、`read-request`、`delete-request` 或 `write-request` 其中之一
response	（可选）指定用于配置解析程序的响应的子策略。如果未指定，将从 Cosmos DB 返回 JSON 格式的响应。	否

connection-info 元素

名称	说明	必需
connection-string	指定 Cosmos DB 帐户的连接字符串。如果配置了API 管理托管标识，请省略帐户密钥。	是
数据库名称 (database-name)	字符串。 Cosmos DB 数据库的名称。	是
container-name	字符串。 Cosmos DB 数据库中容器的名称。	是

connection-string 属性

特征	说明	必需	默认
use-managed-identity	布尔值。指定是否使用 API 管理实例的系统分配的托管标识代替连接字符串中的账户密钥，来连接到 Cosmos DB 账户。必须配置该标识才能访问 Cosmos DB 容器。	否	`false`

query-request 属性

特征	说明	必需	默认
enable-low-precision-order-by	布尔值。指定是否在 Cosmos DB 服务中启用 EnableLowPrecisionOrderBy 查询请求属性。	否	空值

query-request 元素

名称	说明	必需
sql-statement	查询请求的 SQL 语句。	否
参数	参数子元素中查询请求的查询参数列表。	否
partition-key	一个 Cosmos DB 分区键，用于将查询路由到容器中的位置。	否
paging	指定用于将查询结果拆分为多个页面的设置。	否

parameter 特性

特征	说明	必需	默认
姓名	字符串。以 @ 表示法表示的参数的名称。	是	空值

分页元素

名称	说明	必需
max-item-count	指定查询返回的最大项数。如果不想限制每次查询执行的结果数，请设置为 -1。	是
continuation-token	指定要附加到查询以获取下一组结果的延续令牌。	是

max-item-count 属性

特征	说明	必需	默认
模板	用于为 `max-item-count` 设置模板化模式。目前唯一支持的值是： - `liquid` - `max-item-count` 将使用 liquid 模板化引擎。	否	空值

continuation-token 属性

特征	说明	必需	默认
模板	用于设置延续令牌的模板化模式。目前唯一支持的值是： - `liquid` - 延续令牌将使用 liquid 模板化引擎。	否	空值

read-request 元素

名称	说明	必需
id	要在容器中读取的项的标识符。	是
partition-key	容器中项位置的分区键。如果使用 `id` 指定，则启用容器中项的快速点读取（键/值查找）。	否

delete-request 属性

特征	说明	必需	默认
一致性级别	字符串。设置删除请求的 Cosmos DB 一致性级别。	否	空值
预触发器	字符串。在 Cosmos DB 容器中注册的预触发函数的标识符。	否	空值
后触发器	字符串。在 Cosmos DB 容器中注册的后触发函数的标识符。	否	空值

delete-request 元素

名称	说明	必需
id	要在容器中删除的项的标识符。	是
partition-key	容器中项位置的分区键。	否
etag	容器中项的实体标记，用于乐观并发控制。	否

write-request 属性

特征	说明	必需	默认
类型	写入请求的类型：`insert`、`replace` 或 `upsert`。	否	`upsert`
一致性级别	字符串。设置写入请求的 Cosmos DB 一致性级别。	否	空值
indexing-directive	确定应如何为容器项编制索引的索引策略。	否	`default`
预触发器	字符串。在 Cosmos DB 容器中注册的预触发函数的标识符。	否	空值
后触发器	字符串。在 Cosmos DB 容器中注册的后触发函数的标识符。	否	空值

write-request 元素

名称	说明	必需
id	容器中项的标识符。	当 `type` 为 `replace` 时，则为“是”。
etag	容器中项的实体标记，用于乐观并发控制。	否
set-body	设置写入请求中的正文。如果未提供，则请求有效负载会将参数映射到 JSON 格式。	否

response 元素

名称	说明	必需
set-body	设置解析程序的响应中的正文。如果未提供，并且返回的 JSON 包含与 GraphQL 架构中的字段匹配的字段名称，则会自动映射字段。	否
publish-event	将事件发布到 GraphQL API 架构中指定的一个或多个订阅。	否

partition-key 属性

特征	说明	必需	默认
数据类型	分区键的数据类型：`string`、`number`、`bool`、`none` 或 `null`。	否	`string`
模板	用于设置分区键的模板化模式。目前唯一支持的值是： - `liquid` - 分区键将使用 liquid 模板化引擎	否	空值

etag 属性

特征	说明	必需	默认
类型	字符串。以下值之一： - `match` - `etag` 值必须与项的系统生成的实体标记匹配 - `no-match` - `etag` 值不一定要与项的系统生成的实体标记匹配	否	`match`
模板	用于设置 etag 的模板化模式。目前唯一支持的值是： - `liquid` - etag 将使用 liquid 模板化引擎	否	空值

使用情况

策略范围：GraphQL 解析程序
网关：经典

使用注意事项

若要使用此策略配置和管理解析程序，请参阅配置 GraphQL 解析程序。
仅当解析架构中匹配的操作类型中的单个字段时，才会调用此策略。

配置托管标识与 Cosmos DB 的集成

可以配置 API 管理系统分配的托管标识来访问 Cosmos DB 帐户，而不是在连接字符串中提供帐户密钥。

按照以下步骤使用 Azure CLI 配置托管标识。

先决条件

在 API 管理实例中启用系统分配的托管标识。在门户中，记下托管标识的对象（主体）ID。
- 如需在本地运行 CLI 参考命令，请安装 Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。
  - 如果使用的是本地安装，请使用 az login 命令登录 Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅使用 Azure CLI 登录。
  - 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展详细信息，请参阅使用 Azure CLI 的扩展。
  - 运行 az version 以查找安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。

用于配置托管标识的 Azure CLI 脚本

# Set variables

# Variable for Azure Cosmos DB account name
cosmosName="<MY-COSMOS-DB-ACCOUNT>"

# Variable for resource group name
resourceGroupName="<MY-RESOURCE-GROUP>"

# Variable for subscription
resourceGroupName="<MY-SUBSCRIPTION-NAME>"

# Set principal variable to the value from Managed identities page of API Management instance in Azure portal
principal="<MY-APIM-MANAGED-ID-PRINCIPAL-ID>"

# Get the scope value of Cosmos DB account
 
scope=$(
    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $cosmosName \
        --subscription $subscriptionName \
        --query id \
        --output tsv
)

# List the built-in Cosmos DB roles
# Currently, the roles aren't visible in the portal

az cosmosdb sql role definition list \
    --resource-group $resourceGroupName \
    --account-name $cosmosName \
    --subscription $subscriptionName \

# Take note of the role you want to assign, such as "Cosmos DB Built-in Data Contributor" in this example

# Assign desired Cosmos DB role to managed identity

az cosmosdb sql role assignment create \
    --resource-group $resourceGroupName \
    --account-name $cosmosName \
    --subscription $subscriptionName \
    --role-definition-name "Cosmos DB Built-in Data Contributor" \
    --principal-id $principal \
    --scope $scope

示例

Cosmos DB 查询请求

以下示例使用对 Cosmos DB 容器的 SQL 查询来解析 GraphQL 查询。

<cosmosdb-data-source>
    <connection-info>
        <connection-string>
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.cn:443/;AccountKey=CONTOSOKEY;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <query-request>
        <sql-statement>SELECT * FROM c </sql-statement>
    </query-request>
</cosmosdb-data-source>

Cosmos DB 读取请求

以下示例使用对 Cosmos DB 容器的点读取请求来解析 GraphQL 查询。与 Cosmos DB 账户的连接使用 API 管理实例的系统分配的托管标识。必须配置该标识才能访问 Cosmos DB 容器。

用于读取请求的 id 和 partition-key 作为查询参数传递，并使用 context.GraphQL.Arguments["id"] 上下文变量进行访问。

<cosmosdb-data-source>
    <connection-info>
        <connection-string use-managed-identity="true">
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.cn:443/;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <read-request>
        <id>
            @(context.GraphQL.Arguments["id"].ToString())
        </id>
        <partition-key>
            @(context.GraphQL.Arguments["id"].ToString())
    <read-request>
</cosmosdb-data-source>

Cosmos DB 删除请求

以下示例通过对 Cosmos DB 容器的删除请求解析 GraphQL 突变。用于删除请求的 id 和 partition-key 作为查询参数传递，并使用 context.GraphQL.Arguments["id"] 上下文变量进行访问。

<cosmosdb-data-source>
    <connection-info>
        <connection-string>
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.cn:443/;AccountKey=CONTOSOKEY;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <delete-request>
        <id>
            @(context.GraphQL.Arguments["id"].ToString())
        </id>
        <partition-key>
            @(context.GraphQL.Arguments["id"].ToString())
        </partition-key>
    </delete-request>
</cosmosdb-data-source>

Cosmos DB 写入请求

以下示例通过对 Cosmos DB 容器的更新插入请求解析 GraphQL 突变。与 Cosmos DB 账户的连接使用 API 管理实例的系统分配的托管标识。必须配置该标识才能访问 Cosmos DB 容器。

用于写入请求的 partition-key 作为查询参数传递，并使用 context.GraphQL.Arguments["id"] 上下文变量进行访问。更新插入请求具有名为“validateInput”的预触发操作。请求正文是使用 liquid 模板映射的。

<cosmosdb-data-source>
    <connection-info>
        <connection-string use-managed-identity="true">
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.cn:443/;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <write-request type="upsert" pre-trigger="validateInput">
        <partition-key>
            @(context.GraphQL.Arguments["id"].ToString())
        </partition-key>
        <set-body template="liquid">
            {"id" : "{{body.arguments.id}}" ,
            "firstName" : "{{body.arguments.firstName}}",
            "intField" : {{body.arguments.intField}} ,
            "floatField" : {{body.arguments.floatField}} ,
            "boolField" : {{body.arguments.boolField}}}
        </set-body>
    </write-request>
</cosmosdb-data-source>

构造 Cosmos DB 查询的参数输入

以下示例演示了使用策略表达式构造 Cosmos DB 参数化查询的方法。根据参数输入的形式选择一个方法。

这些示例基于以下示例 GraphQL 架构，并生成相应的 Cosmos DB 参数化查询。

示例 GraphQL 架构

input personInput {
  id: String!
  firstName: String
}

type Query {
  personsStringParam(stringInput: String): personsConnection
  personsPersonParam(input: personInput): personsConnection
}

示例 Cosmos DB 查询

{
    "query": "query { 
        personsPersonParam(input: { id: \"3\" } { 
        items { id firstName lastName } 
        } 
    }"
}

从表达式传递 JSON 对象 (JObject)

示例策略

[...]
<query-request>
    <sql-statement>SELECT * FROM c where c.familyId =@param.id</sql-statement>
    <parameters>
        <parameter name="@param">@(context.GraphQL.Arguments["input"])</parameter>
    </parameters>
    </query-request>
[...]

从表达式传递 .NET 输入类型（字符串、整数、小数、布尔）

示例策略

[...]
<query-request>
    <sql-statement>SELECT * FROM c where c.familyId =@param</sql-statement>
    <parameters>
        <parameter name="@param">@($"start.{context.GraphQL.Arguments["stringInput"]}")</parameter>
    </parameters>
</query-request>
[...]

从表达式传递 JSON 值 (JValue)

示例策略

[...]
<query-request>
    <sql-statement>SELECT * FROM c where c.familyId =@param</sql-statement>
    <parameters>
        <parameter name="@param">@(context.GraphQL.Arguments["stringInput"])</parameter>
    </parameters>
</query-request>
[...]

GraphQL 解析程序

后续步骤

有关使用策略的详细信息，请参阅：

教程：转换和保护 API
策略参考，其中提供了策略语句及其设置的完整列表
策略表达式
设置或编辑策略
策略示例

通过

解析程序的 Cosmos DB 数据源

策略语句

元素

connection-info 元素

connection-string 属性

query-request 属性

query-request 元素

parameter 特性

分页元素

max-item-count 属性

continuation-token 属性

read-request 元素

delete-request 属性

delete-request 元素

write-request 属性

write-request 元素

response 元素

partition-key 属性

etag 属性

使用情况

使用注意事项

配置托管标识与 Cosmos DB 的集成

先决条件

用于配置托管标识的 Azure CLI 脚本

示例

Cosmos DB 查询请求

Cosmos DB 读取请求

Cosmos DB 删除请求

Cosmos DB 写入请求

构造 Cosmos DB 查询的参数输入

从表达式传递 JSON 对象 (JObject)

从表达式传递 .NET 输入类型（字符串、整数、小数、布尔）

从表达式传递 JSON 值 (JValue)

相关策略

后续步骤

其他资源