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.

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 de connection-info

atributos de connection-string

atributos query-request

elementos query-request

atributos de parâmetro

elementos de paginação

atributo max-item-count

atributo continuation-token

elementos read-request

atributos delete-request

elementos delete-request

atributos write-request

elementos write-request

elementos de resposta

atributos partition-key

Atributo etag

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
• Kit de ferramentas de políticas do Gerenciamento de API do Azure
• Criar políticas usando o Microsoft Copilot no Azure