Fonte de dados Cosmos DB para um resolvedor

APLICA-SE A: Desenvolvedor | Básico | Básico v2 | Padrão | Standard v2 | Premium | Premium v2

A política de resolvedores cosmosdb-data-source resolve dados para um tipo de objeto e um campo em um esquema GraphQL usando uma fonte de dados do Cosmos DB. O esquema deve ser importado para o Gerenciamento de API como uma API do GraphQL.

Use a política para configurar uma única solicitação de consulta, solicitação de leitura, solicitação de exclusão ou solicitação de gravação e uma resposta opcional da fonte de dados do Cosmos DB.

Observação

Essa política está em versão prévia. Atualmente, não há suporte para a política na camada de Consumo de Gerenciamento de API.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

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

Elementos

Nome	Descrição	Obrigatório
informações de conexão	Especifica a conexão com o contêiner no banco de dados do Cosmos DB.	Yes
query-request	Especifica as configurações de uma solicitação de consulta ao contêiner do Cosmos DB.	Configurar um dos query-request, read-request, delete-requestou write-request
read-request	Especifica as configurações de uma solicitação de leitura ao contêiner do Cosmos DB.	Configurar um dos query-request, read-request, delete-requestou write-request
delete-request	Especifica as configurações de uma solicitação de exclusão ao contêiner do Cosmos DB.	Configurar um dos query-request, read-request, delete-requestou write-request
write-request	Especifica as configurações de uma solicitação de gravação ao contêiner do Cosmos DB.	Configurar um dos query-request, read-request, delete-requestou write-request
response	Opcionalmente, especifica políticas filho para configurar a resposta do resolvedor. Se não for especificada, a resposta será retornada do Cosmos DB como JSON.	Não

elementos de connection-info

Nome	Descrição	Obrigatório
connection-string	Especifica a cadeia de conexão para a conta do Cosmos DB. Se uma identidade gerenciada do Gerenciamento de API estiver configurada, omita a chave da conta.	Sim
database-name	Cadeia de caracteres. Nome do banco de dados do Cosmos DB.	Yes
container-name	Cadeia de caracteres. Nome do contêiner no banco de dados do Cosmos DB.	Sim

atributos de connection-string

Atributo	Descrição	Obrigatório	Padrão
use-managed-identity	Booliano. Especifica se a identidade gerenciada atribuída pelo sistema da instância do Gerenciamento de API deve ser usada para conexão com a conta do Cosmos DB no lugar de uma chave de conta na cadeia de conexão. A identidade deve ser configurada para acessar o contêiner do Cosmos DB.	Não	false

atributos query-request

Atributo	Descrição	Obrigatório	Padrão
enable-low-precision-order-by	Booliano. Especifica se a propriedade de solicitação de consulta EnableLowPrecisionOrderBy deve ser habilitada no serviço do Cosmos DB.	Não	N/D

elementos query-request

Nome	Descrição	Obrigatório
sql-statement	Uma instrução SQL para a solicitação de consulta.	Não
parâmetros	Uma lista de parâmetros de consulta, em subelementos de parâmetro, para a solicitação de consulta.	Não
partition-key	Uma chave de partição do Cosmos DB para rotear a consulta para o local no contêiner.	Não
paging	Especifica as configurações para dividir os resultados da consulta em várias páginas.	Não

atributos de parâmetro

Atributo	Descrição	Obrigatório	Padrão
name	Cadeia de caracteres. Nome do parâmetro em @ notação.	Yes	N/D

elementos de paginação

Nome	Descrição	Obrigatório
max-item-count	Especifica o número máximo de itens retornados pela consulta. Defina como -1 se não quer inserir um limite no número de resultados por execução de consulta.	Sim
continuation-token	Especifica o token de continuação a ser anexado à consulta para obter o próximo conjunto de resultados.	Yes

atributo max-item-count

Atributo	Descrição	Obrigatório	Padrão
template	Usado para definir o modo de modelagem para o max-item-count. Atualmente, o único valor aceito é: - liquid - o max-item-count mecanismo de modelagem líquida é usado.	No	N/D

atributo continuation-token

Atributo	Descrição	Obrigatório	Padrão
template	Usado para definir o modo de modelagem para o token de continuação. Atualmente, o único valor aceito é: - liquid - o token de continuação usa o mecanismo de modelagem líquida.	No	N/D

elementos read-request

Nome	Descrição	Obrigatório
id	Identificador do item a ser lido no contêiner.	Sim
partition-key	Uma chave de partição para o local do item no contêiner. Se especificado com id, habilita uma leitura rápida de ponto (pesquisa de chave/valor) do item no contêiner.	Não

atributos delete-request

Atributo	Descrição	Obrigatório	Padrão
consistency-level	Cadeia de caracteres. Define o nível de consistência do Cosmos DB da solicitação de exclusão.	Não	N/D
Pré-gatilho	Cadeia de caracteres. Identificador de uma função de pré-gatilho registrada no contêiner do Cosmos DB.	Não	N/D
Pós-gatilho	Cadeia de caracteres. Identificador de uma função de pós-gatilho registrada no contêiner do Cosmos DB.	Não	N/D

elementos delete-request

Nome	Descrição	Obrigatório
id	Identificador do item a ser excluído no contêiner.	Sim
partition-key	Uma chave de partição para o local do item no contêiner.	Não
etag	A marca da entidade para o item no contêiner, usada para controle de simultaneidade otimista.	Não

atributos write-request

Atributo	Descrição	Obrigatório	Padrão
type	O tipo de solicitação de gravação: insert, replaceou upsert.	Não	upsert
consistency-level	Cadeia de caracteres. Define o nível de consistência do Cosmos DB da solicitação de gravação.	Não	N/D
indexing-directive	A política de indexação que determina como os itens do contêiner devem ser indexados.	Não	default
Pré-gatilho	Cadeia de caracteres. Identificador de uma função de pré-gatilho registrada no contêiner do Cosmos DB.	Não	N/D
Pós-gatilho	Cadeia de caracteres. Identificador de uma função de pós-gatilho registrada no contêiner do Cosmos DB.	Não	N/D

elementos write-request

Nome	Descrição	Obrigatório
id	Identificador do item no contêiner.	Sim, quando type é replace.
etag	A marca da entidade para o item no contêiner, usada para controle de simultaneidade otimista.	Não
set-body	Define o corpo na solicitação de gravação. Se não for fornecido, o conteúdo da solicitação mapeará os argumentos para o formato JSON.	Não

elementos de resposta

Nome	Descrição	Obrigatório
set-body	Define o corpo na resposta do resolvedor. Se não for fornecido e o JSON retornado contiver nomes de campos correspondentes aos campos no esquema GraphQL, os campos serão mapeados automaticamente.	Não
publish-event	Publica um evento em uma ou mais assinaturas especificadas no esquema da API do GraphQL.	Não

atributos partition-key

Atributo	Descrição	Obrigatório	Padrão
{1>data-type<1}	O tipo de dados da chave de partição: string, number, bool, none ou null.	Não	string
template	Usado para definir o modo de modelagem para a chave de partição. Atualmente, o único valor aceito é: - liquid - a chave de partição usa o mecanismo de modelagem líquida	No	N/D

Atributo etag

Atributo	Descrição	Obrigatório	Padrão
type	Cadeia de caracteres. Um dos seguintes valores: - match – o valor etag deve corresponder à marca de entidade gerada pelo sistema para o item - no-match – o valor etag não precisa corresponder à marca de entidade gerada pelo sistema para o item	Não	match
template	Usado para definir o modo de modelagem para a etag. Atualmente, o único valor aceito é: - liquid - a etag usa o mecanismo de modelagem líquida	No	N/D

Uso

• Escopos de política: resolvedor do GraphQL
• Gateways: clássico, v2

Observações de uso

• Para configurar e gerenciar um resolvedor com essa política, confira Configurar um resolvedor do GraphQL.
• Essa política é invocada somente ao resolver um único campo em um tipo de operação correspondente no esquema.

Configurar a integração de identidade gerenciada com o Cosmos DB

Você pode configurar uma identidade gerenciada atribuída pelo sistema de Gerenciamento de API para acessar uma conta do Cosmos DB, em vez de fornecer uma chave de conta na cadeia de conexão.

Siga estas etapas para usar a CLI do Azure para configurar a identidade gerenciada.

Pré-requisitos

• Habilite uma identidade gerenciada atribuída pelo sistema na instância do Gerenciamento de API. No portal, observe a ID do objeto (entidade de segurança) da identidade gerenciada.

• • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.

    

  • Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.

    • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Script da CLI do Azure para configurar a identidade gerenciada

# 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    

Exemplos

Solicitação de consulta do Cosmos DB

O exemplo a seguir resolve uma consulta GraphQL usando uma consulta SQL para um contêiner do Cosmos DB.

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

Solicitação de leitura do Cosmos DB

O exemplo a seguir resolve uma consulta GraphQL usando uma solicitação de leitura de ponto para um contêiner do Cosmos DB. A conexão com a conta do Cosmos DB usa a identidade gerenciada atribuída pelo sistema da instância do Gerenciamento de API. A identidade deve ser configurada para acessar o contêiner do Cosmos DB.

id e partition-key usados para a solicitação de leitura são passados como parâmetros de consulta e acessados usando a variável de contexto 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>

Solicitação de exclusão do Cosmos DB

O exemplo a seguir resolve uma mutação do GraphQL por uma solicitação de exclusão de um contêiner do Cosmos DB. id e partition-key usados para a solicitação de exclusão são passados como parâmetros de consulta e acessados usando a variável de contexto 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>

Solicitação de gravação do Cosmos DB

O exemplo a seguir resolve uma mutação do GraphQL por uma solicitação de upsert de um contêiner do Cosmos DB. A conexão com a conta do Cosmos DB usa a identidade gerenciada atribuída pelo sistema da instância do Gerenciamento de API. A identidade deve ser configurada para acessar o contêiner do Cosmos DB.

partition-key usado para a solicitação de gravação é passado como um parâmetro de consulta e acessado usando a variável de contexto context.GraphQL.Arguments["id"]. A solicitação upsert tem uma operação de pré-gatilho chamada "validateInput". O corpo da solicitação é mapeado usando um modelo líquido.

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

Construir entrada de parâmetro para a consulta do Cosmos DB

Os exemplos a seguir mostram maneiras de construir consultas parametrizadas no Cosmos DB usando expressões de política. Escolha um método com base na forma da entrada do seu parâmetro.

Os exemplos são baseados na amostra de esquema GraphQL a seguir e geram a consulta parametrizada correspondente do Cosmos DB.

Exemplo de esquema GraphQL

input personInput {
  id: String!
  firstName: String
}

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

Exemplo de consulta do Cosmos DB

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

Passar objeto JSON (JObject) da expressão

Política de exemplo

[...]
<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>
[...]

Passar o tipo de entrada do .NET (string, int, decimal, bool) da expressão

Política de exemplo

[...]
<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>
[...]

Passar o valor JSON (JValue) da expressão

Política de exemplo

[...]
<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>
[...]

Políticas relacionadas

• Resolvedores do GraphQL

Conteúdo relacionado

Para obter mais informações sobre como trabalhar com políticas, consulte:

• Tutorial: Transformar e proteger sua API
• Referência de Política para uma lista completa das instruções de política e suas configurações
• Expressões de política
• Definir ou editar políticas
• Reutilizar configurações de política
• Repositório de snippets de política
• Criar políticas usando o Microsoft Copilot no Azure