Compartir vía


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.
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.
database-name String. Nombre de la base de datos de Cosmos DB.
container-name String. Nombre del contenedor en la base de datos de Cosmos DB.

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 @. 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.
continuation-token Especifica el token de continuación que se va a adjuntar a la consulta para obtener el siguiente conjunto de resultados.

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

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.

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

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