Fonte de dados do Cosmos DB para um resolvedor

  • Artigo

APLICA-SE A: Developer | Básico | Básico v2 | Padrão | Padrão v2 | Prémio

A cosmosdb-data-source política de resolvedor resolve dados para um tipo de objeto e 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 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.

Nota

Esta política está em pré-visualização. Atualmente, a política não é suportada na camada Consumo do Gerenciamento de API.

Nota

Defina os elementos da política e os elementos filho na ordem fornecida na declaração de política. Saiba mais sobre como definir ou editar 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
connection-info Especifica a conexão com o contêiner no banco de dados do Cosmos DB. Sim
consulta-pedido Especifica as configurações de uma solicitação de consulta para o contêiner do Cosmos DB. Configure um dos query-request, read-request, delete-request, ou write-request
leitura-pedido Especifica as configurações de uma solicitação de leitura para o contêiner do Cosmos DB. Configure um dos query-request, read-request, delete-request, ou write-request
excluir-solicitar Especifica as configurações de uma solicitação de exclusão para o contêiner do Cosmos DB. Configure um dos query-request, read-request, delete-request, ou write-request
gravação-solicitação Especifica as configurações de uma solicitação de gravação no contêiner do Cosmos DB. Configure um dos query-request, read-request, delete-request, ou write-request
resposta Opcionalmente, especifica políticas filho para configurar a resposta do resolvedor. Se não for especificado, a resposta será retornada do Cosmos DB como JSON. Não

elementos 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 pelo Gerenciamento de API estiver configurada, omita a chave da conta. Sim
nome do banco de dados String. Nome do banco de dados do Cosmos DB. Sim
container-name String. Nome do contêiner no banco de dados do Cosmos DB. Sim

atributos de cadeia de conexão

Atributo Description Necessário Predefinição
identidade gerenciada por uso Booleano. Especifica se a identidade gerenciada atribuída pelo sistema da instância de 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 Description Necessário Predefinição
habilitar-baixa-precisão-ordem-por Booleano. Especifica se a propriedade de solicitação de consulta EnableLowPrecisionOrderBy deve ser habilitada no serviço Cosmos DB. No N/A

elementos query-request

Nome Descrição Obrigatório
instrução sql 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
chave de partição Uma chave de partição do Cosmos DB para rotear a consulta para o local no contêiner. Não
paginação Especifica as configurações para dividir os resultados da consulta em várias páginas. Não

atributos de parâmetro

Atributo Description Necessário Predefinição
nome String. Nome do parâmetro na notação @. Sim N/A

elementos de paginação

Nome Descrição Obrigatório
contagem máxima de itens Especifica o número máximo de itens retornados pela consulta. Defina como -1 se não quiser colocar um limite no número de resultados por execução de consulta. Sim
token de continuação Especifica o token de continuação a ser anexado à consulta para obter o próximo conjunto de resultados. Sim

atributo max-item-count

Atributo Description Necessário Predefinição
aninhado Usado para definir o modo de modelagem para o max-item-count. Atualmente, o único valor suportado é:

- liquid - o max-item-count utilizará o motor de modelos líquidos.		 No N/A

atributo continuation-token

Atributo Description Necessário Predefinição
aninhado Usado para definir o modo de modelagem para o token de continuação. Atualmente, o único valor suportado é:

- liquid - O token de continuação usará o mecanismo de modelagem Liquid.		 No N/A

elementos de solicitação de leitura

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

atributos delete-request

Atributo Description Necessário Predefinição
nível de consistência String. Define o nível de consistência do Cosmos DB da solicitação de exclusão. No N/A
pré-gatilho String. Identificador de uma função de pré-gatilho registrada no contêiner do Cosmos DB. No N/A
pós-gatilho String. Identificador de uma função pós-gatilho registrada em seu contêiner do Cosmos DB. No N/A

elementos delete-request

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

atributos write-request

Atributo Description Necessário Predefinição
tipo O tipo de solicitação de gravação: insert, replace, ou upsert. Não upsert
nível de consistência String. Define o nível de consistência do Cosmos DB da solicitação de gravação. No N/A
Diretiva de indexação A política de indexação que determina como os itens do contêiner devem ser indexados. Não default
pré-gatilho String. Identificador de uma função de pré-gatilho registrada no contêiner do Cosmos DB. No N/A
pós-gatilho String. Identificador de uma função pós-gatilho registrada em seu contêiner do Cosmos DB. No N/A

elementos write-request

Nome Descrição Obrigatório
id Identificador do item no contêiner. Sim, quando type é replace.
etag Tag de entidade para o item no contêiner, usada para controle de simultaneidade otimista. Não
corpo-conjunto Define o corpo na solicitação de gravação. Se não for fornecida, a carga útil da solicitação mapeará argumentos para o formato JSON. Não

elementos de resposta

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

atributos de chave de partição

Atributo Description Necessário Predefinição
tipo de dados O tipo de dados da chave de partição: string, number, bool, none, ou null. Não string
aninhado Usado para definir o modo de modelagem para a chave de partição. Atualmente, o único valor suportado é:

- liquid - a chave de partição usará o mecanismo de modelagem líquida		 No N/A

atributo etag

Atributo Description Necessário Predefinição
tipo String. Um dos seguintes valores:

- match - o etag valor deve corresponder à tag de entidade gerada pelo sistema para o item

- no-match - o etag valor não é necessário para corresponder à tag de entidade gerada pelo sistema para o item		 Não match
aninhado Usado para definir o modo de modelagem para o etag. Atualmente, o único valor suportado é:

- liquid - o etag utilizará o motor de modelos líquidos		 No N/A

Utilização

Notas de utilização

  • Para configurar e gerenciar um resolvedor com essa política, consulte Configurar um resolvedor 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 ao 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 ao sistema em sua instância de Gerenciamento de API. No portal, anote o ID do objeto (principal) da identidade gerenciada.

    • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

    • Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

      • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

      • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

      • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando 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 pontual 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 de Gerenciamento de API. A identidade deve ser configurada para acessar o contêiner do Cosmos DB.

Os 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 context.GraphQL.Arguments["id"] contexto.

<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 GraphQL por uma solicitação de exclusão para um contêiner do Cosmos DB. Os 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 context.GraphQL.Arguments["id"] contexto.

<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 GraphQL por uma solicitação upsert 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 de Gerenciamento de API. A identidade deve ser configurada para acessar o contêiner do Cosmos DB.

O partition-key usado para a solicitação de gravação é passado como um parâmetro de consulta e acessado usando a variável de context.GraphQL.Arguments["id"] contexto. 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 consulta do Cosmos DB

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

Os exemplos são baseados no esquema GraphQL de exemplo 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

Exemplo de política

[...]
<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 .NET (string, int, decimal, bool) da expressão

Exemplo de política

[...]
<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 valor JSON (JValue) da expressão

Exemplo de política

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

Conteúdos relacionados

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