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 , none o 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
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 mediante Microsoft Copilot en Azure