解析程序的 Cosmos DB 数据源

适用范围：开发人员 | 基本 | 基本 v2 | 标准 | 标准 v2 | 高级 | 高级 v2

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 解析程序
• 网关：经典、v2

使用注意事项

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

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

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

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

先决条件

• 在 API 管理实例中启用系统分配的托管标识。 在门户中，记下托管标识的对象（主体）ID。

• • 在 Azure Cloud Shell 中使用 Bash 环境。 有关详细信息，请参阅 Azure Cloud Shell 入门。

    

  • 如需在本地运行 CLI 参考命令，请安装 Azure CLI。 如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。 有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。

    • 如果使用的是本地安装，请使用 az login 命令登录 Azure CLI。 若要完成身份验证过程，请遵循终端中显示的步骤。 有关其他登录选项，请参阅 使用 Azure CLI 向 Azure 进行身份验证。

    • 出现提示时，请在首次使用时安装 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.com: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.com: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.com: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.com: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
• 策略参考，其中提供了策略语句及其设置的完整列表
• 策略表达式
• 设置或编辑策略
• 重复使用策略配置
• 策略片段存储库
• 策略场存储库
• Azure API 管理策略工具包
• 获取 Copilot 帮助以创建、解释策略和排查策略问题