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.

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

Éléments connection-info

Attributs connection-string

Attributs query-request

Éléments query-request

attributs de paramètre

Éléments paging

Attribut max-item-count

Attribut continuation-token

Éléments read-request

Attributs delete-request

Éléments delete-request

Attributs write-request

Éléments write-request

Éléments response

Attributs partition-key

Attribut etag

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
• Kit de ressources des stratégies Gestion des API Azure
• Créer des stratégies à l’aide de Microsoft Copilot dans Azure