Compartir a través de

解析程序的 Cosmos DB 数据源

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-requestread-requestdelete-requestwrite-request 其中之一
read-request 指定对 Cosmos DB 容器的读取请求的设置。 配置 query-requestread-requestdelete-requestwrite-request 其中之一
delete-request 指定对 Cosmos DB 容器的删除请求的设置。 配置 query-requestread-requestdelete-requestwrite-request 其中之一
write-request 指定对 Cosmos DB 容器的写入请求的设置。 配置 query-requestread-requestdelete-requestwrite-request 其中之一
response (可选)指定用于配置解析程序的响应的子策略。 如果未指定,将从 Cosmos DB 返回 JSON 格式的响应。

connection-info 元素

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

connection-string 属性

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

query-request 属性

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

query-request 元素

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

parameter 特性

Attribute 说明 需要 默认
name 字符串。 以 @ 表示法表示的参数的名称。 空值

分页元素

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

max-item-count 属性

Attribute 说明 需要 默认
template 用于为 max-item-count 设置模板化模式。 目前唯一支持的值是:

- liquid - max-item-count 将使用 liquid 模板化引擎。
空值

continuation-token 属性

Attribute 说明 需要 默认
template 用于设置延续令牌的模板化模式。 目前唯一支持的值是:

- liquid - 延续令牌将使用 liquid 模板化引擎。
空值

read-request 元素

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

delete-request 属性

Attribute 说明 需要 默认
consistency-level 字符串。 设置删除请求的 Cosmos DB 一致性级别 空值
pre-trigger 字符串。 在 Cosmos DB 容器中注册的预触发函数的标识符。 空值
post-trigger 字符串。 在 Cosmos DB 容器中注册的后触发函数的标识符。 空值

delete-request 元素

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

write-request 属性

Attribute 说明 需要 默认
类型 写入请求的类型:insertreplaceupsert upsert
consistency-level 字符串。 设置写入请求的 Cosmos DB 一致性级别 空值
indexing-directive 确定应如何为容器项编制索引的索引策略 default
pre-trigger 字符串。 在 Cosmos DB 容器中注册的预触发函数的标识符。 空值
post-trigger 字符串。 在 Cosmos DB 容器中注册的后触发函数的标识符。 空值

write-request 元素

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

response 元素

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

partition-key 属性

Attribute 说明 需要 默认
data-type 分区键的数据类型:stringnumberboolnonenull string
template 用于设置分区键的模板化模式。 目前唯一支持的值是:

- liquid - 分区键将使用 liquid 模板化引擎
空值

etag 属性

Attribute 说明 需要 默认
type 字符串。 以下值之一:

- match - etag 值必须与项的系统生成的实体标记匹配

- no-match - etag 值不一定要与项的系统生成的实体标记匹配
match
template 用于设置 etag 的模板化模式。 目前唯一支持的值是:

- liquid - etag 将使用 liquid 模板化引擎
空值

使用情况

使用注意事项

  • 若要使用此策略配置和管理解析程序,请参阅配置 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 容器。

用于读取请求的 idpartition-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 突变。 用于删除请求的 idpartition-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>
[...]

后续步骤

有关使用策略的详细信息,请参阅: