Fonte de dados do Cosmos DB para um resolvedor

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.

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

elementos connection-info

atributos de cadeia de conexão

atributos query-request

elementos query-request

atributos de parâmetro

elementos de paginação

atributo max-item-count

atributo continuation-token

elementos de solicitação de leitura

atributos delete-request

elementos delete-request

atributos write-request

elementos write-request

elementos de resposta

atributos de chave de partição

atributo etag

Utilização

• Escopos da política: Resolvedor GraphQL
• Gateways: clássico, v2

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

Políticas relacionadas

• Resolvedores GraphQL

Conteúdos relacionados

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

• Tutorial: Transforme e proteja sua API
• Referência de política para uma lista completa de declarações de política e suas configurações
• Expressões de política
• Definir ou editar políticas
• Reutilizar configurações de política
• Recompra de trechos de política
• Criar políticas usando o Microsoft Copilot no Azure