Source de données Cosmos DB pour un programme de résolution

S’applique à : Développeur | Essentiel | Essentiel v2 | Standard | Standard v2 | Premium | Premium v2

La stratégie de programme de résolution cosmosdb-data-source permet de résoudre les données d’un type et d’un champ d’objet dans un schéma GraphQL à l’aide d’une source de données Cosmos DB. Le schéma doit être importé dans Gestion des API en tant qu’API GraphQL.

Utilisez la stratégie pour configurer une requête d’interrogation, une requête de lecture, une requête de suppression ou une requête d’écriture unique et une réponse facultative de la source de données Cosmos DB.

Notes

Cette stratégie est en préversion. Actuellement, la stratégie n’est pas prise en charge dans le niveau Consommation de Gestion des API.

Notes

Définissez les éléments enfants et de stratégie dans l’ordre fourni dans l’instruction de stratégie. En savoir plus sur comment définir ou modifier des stratégies du service Gestion des API.

Instruction de la stratégie

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

Éléments

Nom	Description	Obligatoire
informations de connexion	Spécifie la connexion au conteneur dans la base de données Cosmos DB.	Oui
query-request	Spécifie les paramètres d’une requête d’interrogation adressée au conteneur Cosmos DB.	Configurez l’un des éléments query-request, read-request, delete-request ou write-request
read-request	Spécifie les paramètres d’une requête de lecture adressée au conteneur Cosmos DB.	Configurez l’un des éléments query-request, read-request, delete-request ou write-request
delete-request	Spécifie les paramètres d’une requête de suppression adressée au conteneur Cosmos DB.	Configurez l’un des éléments query-request, read-request, delete-request ou write-request
write-request	Spécifie les paramètres d’une requête d’écriture adressée au conteneur Cosmos DB.	Configurez l’un des éléments query-request, read-request, delete-request ou write-request
response	(Facultatif) Spécifie les stratégies enfants pour configurer la réponse du programme de résolution. Si elle n’est pas spécifiée, la réponse est retournée à partir de Cosmos DB au format JSON.	Non

Éléments connection-info

Nom	Description	Obligatoire
connection-string	Spécifie la chaîne de connexion pour le compte Cosmos DB. Si une identité managée Gestion des API est configurée, omettez la clé de compte.	Oui
database-name	Chaîne. Nom de la base de données Cosmos DB.	Oui
container-name	Chaîne. Nom du conteneur dans la base de données Cosmos DB.	Oui

Attributs connection-string

Attribut	Description	Obligatoire	Default
use-managed-identity	Propriété booléenne. Spécifie s’il faut utiliser l’identité managée affectée par le système de l’instance Gestion des API pour la connexion au compte Cosmos DB au lieu d’une clé de compte dans la chaîne de connexion. L’identité doit être configurée pour accéder au conteneur Cosmos DB.	Non	false

Attributs query-request

Attribut	Description	Obligatoire	Default
enable-low-precision-order-by	Propriété booléenne. Spécifie s’il faut activer la propriété de requête d’interrogation EnableLowPrecisionOrderBy dans le service Cosmos DB.	Non	N/A

Éléments query-request

Nom	Description	Obligatoire
sql-statement	Instruction SQL pour la requête d’interrogation.	Non
parameters	Liste des paramètres de requête, dans les sous-éléments parameter, pour la requête d’interrogation.	Non
partition-key	Clé de partition Cosmos DB pour acheminer la requête vers l’emplacement dans le conteneur.	Non
paging	Spécifie les paramètres pour fractionner les résultats de la requête en plusieurs pages.	Non

attributs de paramètre

Attribut	Description	Obligatoire	Default
name	Chaîne. Nom du paramètre en notation @.	Oui	N/A

Éléments paging

Nom	Description	Obligatoire
max-item-count	Spécifie le nombre maximal d’éléments retournés par la requête. Définissez cet élément sur la valeur -1 si vous ne voulez pas limiter le nombre de résultats par exécution de requête.	Oui
continuation-token	Spécifie le jeton de continuation à attacher à la requête pour obtenir le jeu de résultats suivant.	Oui

Attribut max-item-count

Attribut	Description	Obligatoire	Default
template	Permet de définir le mode de templating pour l’élément max-item-count. Actuellement, la seule valeur possible est : - liquid : le max-item-count utilise le moteur de templating liquide.	Non	N/A

Attribut continuation-token

Attribut	Description	Obligatoire	Default
template	Permet de définir le mode de templating pour le jeton de continuation. Actuellement, la seule valeur possible est : - liquid : le jeton de continuation utilise le moteur de templating liquide.	Non	N/A

Éléments read-request

Nom	Description	Obligatoire
id	Identificateur de l’élément à lire dans le conteneur.	Oui
partition-key	Clé de partition de l’emplacement de l’élément dans le conteneur. Si cet élément est spécifié avec id, active une lecture de point rapide (recherche clé/valeur) de l’élément dans le conteneur.	Non

Attributs delete-request

Attribut	Description	Obligatoire	Default
consistency-level	Chaîne. Définit le niveau de cohérence Cosmos DB de la requête de suppression.	Non	N/A
pre-trigger	Chaîne. Identificateur d’une fonction de pré-déclencheur inscrite dans votre conteneur Cosmos DB.	Non	N/A
post-trigger	Chaîne. Identificateur d’une fonction de post-déclencheur inscrite dans votre conteneur Cosmos DB.	Non	N/A

Éléments delete-request

Nom	Description	Obligatoire
id	Identificateur de l’élément à supprimer dans le conteneur.	Oui
partition-key	Clé de partition de l’emplacement de l’élément dans le conteneur.	Non
etag	Étiquette d’entité de l’élément dans le conteneur, utilisée pour le contrôle d’accès concurrentiel optimiste.	Non

Attributs write-request

Attribut	Description	Obligatoire	Default
type	Type de requête d’écriture : insert, replace ou upsert.	Non	upsert
consistency-level	Chaîne. Définit le niveau de cohérence Cosmos DB de la requête d’écriture.	Non	N/A
indexing-directive	Stratégie d’indexation qui détermine la façon dont les éléments du conteneur doivent être indexés.	Non	default
pre-trigger	Chaîne. Identificateur d’une fonction de pré-déclencheur inscrite dans votre conteneur Cosmos DB.	Non	N/A
post-trigger	Chaîne. Identificateur d’une fonction de post-déclencheur inscrite dans votre conteneur Cosmos DB.	Non	N/A

Éléments write-request

Nom	Description	Obligatoire
id	Identificateur de l’élément dans le conteneur.	Oui quand type est replace.
etag	Étiquette d’entité de l’élément dans le conteneur, utilisée pour le contrôle d’accès concurrentiel optimiste.	Non
set-body	Définit le corps de la requête d’écriture. Si cet élément n’est pas fourni, la charge utile de la requête mappe les arguments au format JSON.	Non

Éléments response

Nom	Description	Obligatoire
set-body	Définit le corps dans la réponse du programme de résolution. Si cet élément n’est pas fourni et que l’objet JSON retourné contient des noms de champs correspondant à des champs dans le schéma GraphQL, les champs sont automatiquement mappés.	Non
publish-event	Publie un événement dans un ou plusieurs abonnements spécifiés dans le schéma de l’API GraphQL.	Non

Attributs partition-key

Attribut	Description	Obligatoire	Default
data-type	Type de données de la clé de partition : string, number, bool, none ou null.	Non	string
template	Permet de définir le mode de templating pour la clé de partition. Actuellement, la seule valeur possible est : - liquid : la clé de partition utilise le moteur de templating liquide	Non	N/A

Attribut etag

Attribut	Description	Obligatoire	Default
type	Chaîne. Une des valeurs suivantes : - match : la valeur etag doit correspondre à l’étiquette d’entité générée par le système pour l’élément - no-match : la valeur etag ne doit pas correspondre à l’étiquette d’entité générée par le système pour l’élément	Non	match
template	Permet de définir le mode de templating pour l’élément etag. Actuellement, la seule valeur possible est : - liquid : l’étiquette d’entité utilise le moteur de templating liquide	Non	N/A

Usage

• Étendues de la stratégie : Résolveur GraphQL
• Passerelles : classiques, v2

Notes d’utilisation

• Pour configurer et gérer un résolveur avec cette stratégie, voir Configurer un résolveur GraphQL.
• Cette stratégie est appelée uniquement lors de la résolution d’un champ unique dans un type d’opération correspondant dans le schéma.

Configurer l’intégration des identités managées à Cosmos DB

Vous pouvez configurer une identité managée affectée par le système Gestion des API pour accéder à un compte Cosmos DB, au lieu de fournir une clé de compte dans la chaîne de connexion.

Pour utiliser Azure CLI pour configurer l’identité managée, procédez comme suit.

Prérequis

• Activez uneidentité managée affectée par le système dans votre instance Gestion des API. Dans le portail, notez l’ID d’objet (principal) de l’identité managée.

• • Utilisez l’environnement Bash dans Azure Cloud Shell. Pour plus d’informations, consultez Démarrage rapide pour Bash dans Azure Cloud Shell.

    

  • Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker. Pour plus d’informations, consultez Guide pratique pour exécuter Azure CLI dans un conteneur Docker.

    • Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login. Pour finir le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour connaître les autres options de connexion, consultez Se connecter avec Azure CLI.

    • Lorsque vous y êtes invité, installez l’extension Azure CLI lors de la première utilisation. Pour plus d’informations sur les extensions, consultez Utiliser des extensions avec Azure CLI.

    • Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.

Script Azure CLI permettant de configurer l’identité managée

# 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    

Exemples

Requête d’interrogation Cosmos DB

L’exemple ci-dessous résout une requête GraphQL à l’aide d’une requête SQL dans un conteneur 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>

Requête de lecture Cosmos DB

L’exemple ci-dessous résout une requête GraphQL à l’aide d’une requête de lecture de point dans un conteneur Cosmos DB. La connexion au compte Cosmos DB utilise l’identité managée affectée par le système de l’instance Gestion des API. L’identité doit être configurée pour accéder au conteneur Cosmos DB.

Les éléments id et partition-key utilisés pour la requête de lecture sont transmis en tant que paramètres de requête et accessibles à l’aide de la variable de contexte 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>

Requête de suppression Cosmos DB

L’exemple ci-dessous résout une mutation GraphQL par une requête de suppression dans un conteneur Cosmos DB. Les éléments id et partition-key utilisés pour la requête de suppression sont transmis en tant que paramètres de requête et accessibles à l’aide de la variable de contexte 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>

Requête d’écriture Cosmos DB

L’exemple ci-dessous résout une mutation GraphQL par une requête d’upsert dans un conteneur Cosmos DB. La connexion au compte Cosmos DB utilise l’identité managée affectée par le système de l’instance Gestion des API. L’identité doit être configurée pour accéder au conteneur Cosmos DB.

L’élément partition-key utilisé pour la requête d’écriture est transmis en tant que paramètre de requête et accessible à l’aide de la variable de contexte context.GraphQL.Arguments["id"]. La requête d’upsert a une opération de pré-déclenchement nommée « validateInput ». Le corps de la requête est mappé à l’aide d’un modèle liquide.

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

Entrée de paramètre de construction pour la requête Cosmos DB

Les exemples suivants montrent comment construire des requêtes paramétrisées Cosmos DB à l’aide d’expressions de stratégie. Choisissez une méthode en fonction de la forme de votre entrée de paramètre.

Les exemples se basent sur l’exemple de schéma GraphQL suivant et génèrent la requête paramétrable Cosmos DB correspondante.

Exemple de schéma GraphQL

input personInput {
  id: String!
  firstName: String
}

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

Exemple de requête Cosmos DB

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

Transmettre un objet JSON (JObject) à partir d’une expression

Exemple de stratégie

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

Transmettre un type d’entrée .NET (string, int, decimal, bool) à partir d’une expression

Exemple de stratégie

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

Transmettre une valeur JSON (JValue) à partir d’une expression

Exemple de stratégie

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

Stratégies connexes

• Résolveurs GraphQL

Contenu connexe

Pour plus d’informations sur l’utilisation des stratégies, consultez :

• Tutoriel : Transformer et protéger votre API
• Référence de stratégie pour obtenir la liste complète des instructions et des paramètres de stratégie
• Expressions de stratégie
• Définir ou modifier des stratégies
• Réutilisation de configurations de stratégie
• Référentiel d’extrait de stratégie
• Créer des stratégies à l’aide de Microsoft Copilot dans Azure