Origen de datos Cosmos DB para una resolución

SE APLICA A: Desarrollador | Básico | Básico v2 | Estándar | Estándar v2 | Premium

La directiva de resolución cosmosdb-data-source resuelve los datos de un tipo de objeto y un campo en un esquema GraphQL mediante un origen de datos de Cosmos DB. El esquema debe importarse a API Management como API de GraphQL.

Use la directiva para configurar una única solicitud de consulta, una solicitud de lectura, una solicitud de eliminación o una solicitud de escritura y una respuesta opcional del origen de datos de Cosmos DB.

Nota

Esta directiva está en versión preliminar. Actualmente, la directiva no se admite en el nivel Consumo de API Management.

Nota

Establezca los elementos de la directiva y los elementos secundarios en el orden proporcionado en la instrucción de directiva. Obtenga más información sobre el establecimiento o modificación de directivas de API Management.

Instrucción de la directiva

<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

Nombre	Descripción	Obligatorio
información de conexión	Especifica la conexión al contenedor en la base de datos de Cosmos DB.	Sí
query-request	Especifica la configuración de una solicitud de consulta al contenedor de Cosmos DB.	Configure de una de las opciones query-request, read-request, delete-request o write-request
read-request	Especifica la configuración de una solicitud de lectura al contenedor de Cosmos DB.	Configure de una de las opciones query-request, read-request, delete-request o write-request
delete-request	Especifica la configuración de una solicitud de eliminación al contenedor de Cosmos DB.	Configure de una de las opciones query-request, read-request, delete-request o write-request
write-request	Especifica la configuración de una solicitud de escritura al contenedor de Cosmos DB.	Configure de una de las opciones query-request, read-request, delete-request o write-request
response	Opcionalmente, especifica las directivas secundarias para configurar la respuesta del solucionador. Si no se especifica, la respuesta se devuelve de Cosmos DB como JSON.	No

connection-info elements

NOMBRE	Descripción	Obligatorio
connection-string	Especifica la cadena de conexión de la cuenta de Cosmos DB. Si se configura una identidad administrada API Management, omita la clave de cuenta.	Sí
database-name	String. Nombre de la base de datos de Cosmos DB.	Sí
container-name	String. Nombre del contenedor en la base de datos de Cosmos DB.	Sí

atributos de connection-string

Atributo	Descripción	Necesario	Valor predeterminado
use-managed-identity	booleano. Especifica si se debe usar la identidad administrada asignada por el sistema de la instancia de API Management para la conexión a la cuenta de Cosmos DB en lugar de una clave de cuenta en la cadena de conexión. La identidad debe configurarse para acceder al contenedor de Cosmos DB.	No	false

atributos de query-request

Atributo	Descripción	Necesario	Valor predeterminado
enable-low-precision-order-by	booleano. Especifica si se va a habilitar la propiedad de solicitud de consulta EnableLowPrecisionOrderBy en el servicio Cosmos DB.	No	N/D

elementos http-query

NOMBRE	Descripción	Obligatorio
sql-statement	Instrucción SQL para la solicitud de consulta.	No
parámetros	Lista de parámetros de consulta, en subelementos de parámetros, para la solicitud de consulta.	No
partition-key	Una clave de partición de Cosmos DB para enrutar la consulta a la ubicación del contenedor.	No
paging	Especifica la configuración para dividir los resultados de la consulta en varias páginas.	No

atributos de parámetro

Atributo	Descripción	Necesario	Valor predeterminado
name	Cadena Nombre del parámetro en la notación @.	Sí	N/D

elementos de paginación

NOMBRE	Descripción	Obligatorio
max-item-count	Especifica el número máximo de elementos devueltos por la consulta. Puede establecerlo en -1 si no desea establecer un límite para el número de resultados por ejecución de consulta.	Sí
continuation-token	Especifica el token de continuación que se va a adjuntar a la consulta para obtener el siguiente conjunto de resultados.	Sí

atributo max-item-count

Atributo	Descripción	Necesario	Valor predeterminado
template	Se usa para establecer el modo de plantillas para max-item-count. Actualmente, el único valor admitido es: - liquid: max-item-count usará el motor de plantillas liquid.	No	N/D

atributo continuation-token

Atributo	Descripción	Necesario	Valor predeterminado
template	Se usa para establecer el modo de plantillas para el token de continuación. Actualmente, el único valor admitido es: - liquid : el token de continuación usará el motor de plantillas líquidas.	No	N/D

elementos read-request

NOMBRE	Descripción	Requerido
id	Identificador del elemento que se va a leer en el contenedor.	Sí
clave de partición	Clave de partición para la ubicación del elemento en el contenedor. Si se especifica con id, habilita una lectura rápida (búsqueda de clave/valor) del elemento en el contenedor.	No

atributos de delete-request

Atributo	Descripción	Necesario	Valor predeterminado
consistency-level	String. Establece el nivel de coherencia de Cosmos DB de la solicitud de eliminación.	No	N/D
pre-trigger	String. Identificador de una función previa al desencadenador registrada en el contenedor de Cosmos DB.	No	N/D
post-trigger	String. Identificador de una función posterior al desencadenador registrada en el contenedor de Cosmos DB.	No	N/D

elementos delete-request

NOMBRE	Descripción	Requerido
id	Identificador del elemento que se va a eliminar en el contenedor.	Sí
clave de partición	Clave de partición para la ubicación del elemento en el contenedor.	No
etag	Etiqueta de entidad para el elemento del contenedor, que se usa para el control de simultaneidad optimista.	No

atributos de write-request

Atributo	Descripción	Necesario	Valor predeterminado
type	Tipo de solicitud de escritura: insert, replace o upsert.	No	upsert
consistency-level	String. Establece el nivel de coherencia de Cosmos DB de la solicitud de escritura.	No	N/D
indexing-directive	Directiva de indexación que determina cómo se deben indexar los elementos del contenedor.	No	default
pre-trigger	String. Identificador de una función previa al desencadenador registrada en el contenedor de Cosmos DB.	No	N/D
post-trigger	String. Identificador de una función posterior al desencadenador registrada en el contenedor de Cosmos DB.	No	N/D

elementos write-request

NOMBRE	Descripción	Requerido
id	Identificador del elemento en el contenedor.	Sí, cuando type es replace.
etag	Etiqueta de entidad para el elemento del contenedor, que se usa para el control de simultaneidad optimista.	No
set-body	Establece el cuerpo de la solicitud de escritura. Si no se proporciona, la carga de la solicitud asignará argumentos al formato JSON.	No

elementos de respuesta

NOMBRE	Descripción	Obligatorio
set-body	Establece el cuerpo en la respuesta de la resolución. Si no se proporciona y el JSON devuelto contiene nombres de campo que coinciden con campos en el esquema GraphQL, los campos se asignan automáticamente.	No
publish-event	Publica un evento en una o varias suscripciones especificadas en el esquema de GraphQL API.	No

atributos de partition-key

Atributo	Descripción	Necesario	Valor predeterminado
data-type	Tipo de datos de la clave de partición: string, number, bool, noneo null.	No	string
template	Se usa para establecer el modo de plantillas para la clave de partición. Actualmente, el único valor admitido es: - liquid: la clave de partición usará el motor de plantillas liquid	No	N/D

atributo etag

Atributo	Descripción	Necesario	Valor predeterminado
type	String. Uno de los siguientes valores: - match : el valor etag debe coincidir con la etiqueta de entidad generada por el sistema para el elemento - no-match : el valor etag no tiene por qué coincidir con la etiqueta de entidad generada por el sistema para el elemento	No	match
template	Se usa para establecer el modo de plantillas para etag. Actualmente, el único valor admitido es: - liquid: etag usará el motor de plantillas liquid	No	N/D

Uso

• Ámbitos de directiva: resolución de GraphQL
• Puertas de enlace: clásica, v2

Notas de uso

• Para configurar y administrar una resolución con esta directiva, consulte Configuración de una resolución de GraphQL.
• Esta directiva solo se invoca al resolver un único campo en un tipo de operación coincidente en el esquema.

Configuración de la integración de identidades administradas con Cosmos DB

Puede configurar una identidad administrada asignada por el sistema API Management para acceder a una cuenta de Cosmos DB, en lugar de proporcionar una clave de cuenta en la cadena de conexión.

Siga estos pasos para usar la CLI de Azure para configurar la identidad administrada.

Prerrequisitos

• Habilite una identidad administrada asignada por el sistema en la instancia de API Management. En el portal, anote el identificador de objeto (entidad de seguridad) de la identidad administrada.

• • Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para Bash en Azure Cloud Shell.

    

  • Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker. Para más información, vea Ejecución de la CLI de Azure en un contenedor de Docker.

    • Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Inicio de sesión con la CLI de Azure.

    • En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para más información sobre las extensiones, consulte Uso de extensiones con la CLI de Azure.

    • Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.

Script de la CLI de Azure para configurar la identidad administrada

# 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    

Ejemplos

solicitud de consulta de Cosmos DB

En el ejemplo siguiente se resuelve una consulta GraphQL mediante una consulta SQL en un contenedor de 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>

solicitud de lectura de Cosmos DB

En el ejemplo siguiente se resuelve una consulta de GraphQL mediante una solicitud de lectura puntual a un contenedor de Cosmos DB. La conexión a la cuenta de Cosmos DB usa la identidad administrada asignada por el sistema de la instancia de API Management. La identidad debe configurarse para acceder al contenedor de Cosmos DB.

id y partition-key se usan para la solicitud de lectura se pasan como parámetros de consulta y se accede a ellos mediante la variable 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>

solicitud de eliminación de Cosmos DB

En el ejemplo siguiente se resuelve una mutación de GraphQL mediante una solicitud de eliminación en un contenedor de Cosmos DB. id y partition-key se usan para la solicitud de eliminación se pasan como parámetros de consulta y se accede a ellos mediante la variable 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>

solicitud de escritura de Cosmos DB

En el ejemplo siguiente se resuelve una mutación de GraphQL mediante una solicitud upsert en un contenedor de Cosmos DB. La conexión a la cuenta de Cosmos DB usa la identidad administrada asignada por el sistema de la instancia de API Management. La identidad debe configurarse para acceder al contenedor de Cosmos DB.

El objeto partition-key utilizado para la solicitud de escritura se pasa como parámetro de consulta y se obtiene acceso a él mediante la variable de contexto context.GraphQL.Arguments["id"]. La solicitud upsert tiene una operación de desencadenador previo denominada "validateInput". El cuerpo de la solicitud se asigna mediante una plantilla líquida.

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

Construcción de la entrada de parámetros para la consulta de Cosmos DB

En los ejemplos siguientes se muestran formas de construir consultas parametrizadas de Cosmos DB mediante expresiones de directiva. Elija un método basado en el formulario de la entrada del parámetro.

Los ejemplos se basan en el siguiente esquema graphQL de ejemplo y generan la consulta con parámetros de Cosmos DB correspondiente.

Esquema de GraphQL de ejemplo

input personInput {
  id: String!
  firstName: String
}

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

Ejemplo de una consulta de Cosmos DB

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

Pasar el objeto JSON (JObject) de la expresión

Ejemplo de directiva

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

Pasar el tipo de entrada de .NET (string, int, decimal, bool) de la expresión

Ejemplo de directiva

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

Pasar el valor JSON (JValue) de la expresión

Ejemplo de directiva

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

Directivas relacionadas

• Solucionadores de GraphQL

Contenido relacionado

Para más información sobre el trabajo con directivas, vea:

• Tutorial: Transformación y protección de una API
• Referencia de directivas para una lista completa de instrucciones de directivas y su configuración
• Expresiones de directiva
• Establecimiento o edición de directivas
• Reutilización de configuraciones de directivas
• Repositorio de fragmentos de código de directiva
• Creación de directivas con Microsoft Copilot para Azure