Partager via


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

S’APPLIQUE À : Développeur | Essentiel | Essentiel v2 | Standard | Standard v2 | Premium

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 : l’élément 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’élément etag utilise le moteur de templating liquide
Non N/A

Usage

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.

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

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