Traiter et créer des documents Azure Cosmos DB à l’aide d’Azure Logic Apps

S’applique à : Azure Logic Apps (Consommation + Standard)

À partir de votre flux de travail dans Azure Logic Apps, vous pouvez vous connecter à Azure Cosmos DB et travailler sur des documents à l’aide du connecteur Azure Cosmos DB. Ce connecteur fournit des déclencheurs et des actions que votre flux de travail peut utiliser pour des effectuer opérations Azure Cosmos DB. Des actions possibles sont, par exemple, la création ou la mise à jour, la lecture, l’interrogation et la suppression de documents.

Vous pouvez vous connecter à Azure Cosmos DB à partir des types de ressources Application logique (Consommation) et Application logique (Standard) à l’aide des opérations de connecteur géré. Pour Application logique (Standard), Azure Cosmos DB fournit également des opérations intégrées, actuellement en préversion, qui offrent d’autres fonctionnalités, de meilleures performances et un débit plus élevé. Par exemple, si vous utilisez le type de ressource Application logique (Standard), vous pouvez utiliser le déclencheur intégré pour répondre aux modifications dans un conteneur Azure Cosmos DB. Vous pouvez combiner des opérations d’Azure Cosmos DB avec d’autres actions et déclencheurs dans vos flux de travail d’application logique pour activer des scénarios tels que l’approvisionnement en événements et le traitement de données générales.

Limites

• Actuellement, seuls des flux de travail avec état dans une ressource de type Application logique (Standard) peuvent utiliser les opérations de connecteur managé et les opérations intégrées. Des flux de travail sans état peuvent utiliser uniquement des opérations intégrées.

• Le connecteur Azure Cosmos DB prend uniquement en charge les comptes Azure Cosmos DB créés avec Azure Cosmos DB for NoSQL.

Prérequis

• Un compte et un abonnement Azure. Si vous n’avez pas d’abonnement Azure, inscrivez-vous pour bénéficier d’un compte Azure gratuit.

• Un compte Azure Cosmos DB.

• Un flux de travail d’application logique à partir duquel vous souhaitez accéder à votre compte Azure Cosmos DB. Pour utiliser le déclencheur Azure Cosmos DB, vous devez créer votre application logique à l’aide du type de ressource Application logique (Standard) et ajouter un flux de travail vide.

Ajouter un déclencheur Azure Cosmos DB

Dans Azure Logic Apps, chaque flux de travail doit commencer par un déclencheur, qui s’active lorsqu’un événement spécifique se produit ou qu’une condition particulière est remplie.

Si vous utilisez le type de ressource Application logique (Standard), le déclencheur intégré nommé Lors de la création ou de la modification d’un élément (préversion) est disponible. Celui-ci est basé sur le modèle de flux de modification Azure Cosmos DB. Ce déclencheur n’est pas disponible pour le type de ressource Application logique (Consommation).

Consommation

Aucun déclencheur Azure Cosmos DB n’est disponible pour le type de ressource Application logique (Consommation).

Standard

Pour ajouter un déclencheur intégré Azure Cosmos DB à un flux de travail d’application logique dans Azure Logic Apps monolocataire, procédez comme suit :

1. Sur le Portail Azure, ouvrez votre flux de travail d’application logique dans le Concepteur.

2. Pour trouver le déclencheur, procédez comme suit :

   1. Dans le concepteur, sélectionnez Choisir une opération.

   2. Une fois le volet Ajouter un déclencheur ouvert, dans la zone de recherche Choisir une opération, sélectionnez Intégrée.

   3. Dans la zone de recherche, entrez Azure Cosmos DB. Dans la liste des déclencheurs, sélectionnez le déclencheur nommé Lors de la création ou de la modification d’un élément (préversion).

   

3. Si vous êtes invité à entrer les informations de connexion, créez une connexion à Azure Cosmos DB maintenant.

4. Sous l’onglet Paramètres, fournissez les informations nécessaires pour le déclencheur.

   Propriété	Obligatoire	Value	Description
   ID de base de données	Oui	<nom-base-de-données>	Nom de la base de données avec le conteneur que vous souhaitez surveiller. Cette base de données doit également comprendre le conteneur de baux. Si vous n’avez pas encore de conteneur de baux, le connecteur en créera un pour vous dans une étape ultérieure.
   ID de conteneur surveillé	Oui	<container-name>	Nom du conteneur que vous souhaitez surveiller. Ce conteneur doit préexister dans la base de données spécifiée.
   ID de conteneur de baux	Oui	<nom-conteneur-baux>	Nom d’un conteneur de baux existant ou d’un nouveau conteneur à créer pour vous. Le déclencheur pré-remplit leases comme nom par défaut commun.
   Créer un conteneur de baux	Non	Non ou Oui	Si le conteneur de baux existe déjà dans la base de données spécifiée, sélectionnez Non. Si vous souhaitez que le déclencheur crée ce conteneur, sélectionnez Oui. Si vous sélectionnez Oui et que vous utilisez le débit manuel dédié à chaque conteneur, veillez à ouvrir la liste Ajouter un nouveau paramètre pour sélectionner la propriété Débit du conteneur de baux. Entrez le nombre d’unités de requête (RU) que vous souhaitez approvisionner pour ce conteneur.

   L’illustration suivante montre un exemple de déclencheur :

   

   Remarque

   Le déclencheur crée plusieurs exécutions de flux de travail pour chaque élément créé ou modifié dans Azure Cosmos DB, de sorte que la sortie de contenu dynamique de ce déclencheur est toujours un élément unique.

5. Ajoutez toutes les autres actions souhaitées à votre flux de travail.

6. Dans la barre d’outils du Concepteur, sélectionnez Enregistrer.

Ajouter une action Azure Cosmos DB

Dans Azure Logic Apps, une action est une étape de votre flux de travail qui suit un déclencheur ou une autre action. Le connecteur Azure Cosmos DB offre des actions pour les types de ressources Application logique (Consommation) et Application logique (Standard). Les exemples suivants pour chaque type de ressource montrent comment utiliser une action qui crée ou met à jour un document.

Consommation

Pour ajouter une action Azure Cosmos DB à un flux de travail d’application logique dans Azure Logic Apps multilocataire, procédez comme suit :

1. Sur le Portail Azure, ouvrez votre flux de travail dans le Concepteur.

2. Si votre flux de travail est vide, ajoutez le déclencheur de votre choix.

   Cet exemple démarre avec le déclencheur Lors de la réception d’une requête HTTP.

3. Sous le déclencheur ou l’action auxquels vous souhaitez ajouter l’action Azure Cosmos DB, sélectionnez Nouvelle étape ou Ajouter une action s’il y a des étapes intermédiaires.

4. Dans la zone de recherche du Concepteur, entrez Azure Cosmos DB. Sélectionnez l’action Azure Cosmos DB que vous souhaitez utiliser.

   Cet exemple utilise l’action nommée Créer ou mettre à jour un document (v3).

   

5. Si vous êtes invité à entrer les informations de connexion, créez une connexion à votre compte Azure Cosmos DB maintenant.

6. Entrez les informations nécessaires pour l’action.

   Propriété	Obligatoire	Value	Description
   Nom de compte Azure Cosmos DB	Oui	Sélectionnez Utiliser les paramètres de connexion (<nom-compte-Azure-Cosmos-DB>), ou entrez le nom manuellement.	Nom de compte de votre compte Azure Cosmos DB.
   ID de base de données	Oui	<ID-base-de-données>	Base de données à laquelle vous souhaitez vous connecter.
   ID de conteneur	Oui	<ID-conteneur>	Conteneur que vous souhaitez interroger.
   Document	Oui	<JSON-document>	Document JSON que vous souhaitez créer. Cet exemple utilise le corps de la demande de la sortie du déclencheur. Conseil : si le jeton Body du déclencheur HTTP ne figure pas dans la liste de contenu dynamique à ajouter, en regard du nom du déclencheur, sélectionnez Afficher plus. Remarque : assurez-vous que le format JSON du corps est correct et qu’il contient au minimum la propriété id et la propriété de clé de partition pour votre document. Si un document avec l’id et la clé de partition spécifiés existe déjà, le document est mis à jour. Sinon, un nouveau document est créé.

   L’illustration suivante montre un exemple d’action :

   

7. Configurez tous les autres paramètres d’action en fonction des besoins.

8. Dans la barre d’outils du Concepteur, sélectionnez Enregistrer.

9. Testez votre application logique pour vous assurer que votre flux de travail crée un document dans le conteneur spécifié.

Standard

Pour ajouter une action Azure Cosmos DB à un flux de travail d’application logique dans Azure Logic Apps monolocataire, procédez comme suit :

1. Sur le Portail Azure, ouvrez votre flux de travail dans le Concepteur.

2. Si votre flux de travail est vide, ajoutez le déclencheur de votre choix.

   Cet exemple commence par le déclencheur Lors de la réception d’une requête HTTP qui utilise une définition de schéma de base pour représenter l’élément que vous souhaitez créer.

   

3. Sous le déclencheur ou l’action à laquelle vous souhaitez ajouter l’action Azure Cosmos DB, sélectionnez Insérer une nouvelle étape (+) >Ajouter une action.

4. Dans le Concepteur, vérifiez que l’option Ajouter une opération est sélectionnée. Dans le volet Ajouter une action qui s’ouvre, sous la zone de recherche Choisir une opération, sélectionnez Intégré pour trouver les actions Azure Cosmos DB.

   Remarque

   Si vous avez un flux de travail avec état, des actions de connecteur managé sont également disponibles sous l’onglet Azure. Ne les utilisez que si les actions intégrées que vous souhaitez ne sont pas disponibles.

5. Dans la zone de recherche, entrez Azure Cosmos DB. Sélectionnez l’action Azure Cosmos DB que vous souhaitez utiliser.

   Cet exemple utilise l’action nommée Créer ou mettre à jour un élément (préversion) qui crée un élément ou met à jour un élément existant.

   

6. Si vous êtes invité à entrer les informations de connexion, créez une connexion à votre compte Azure Cosmos DB maintenant.

7. Entrez les informations nécessaires pour l’action.

   Propriété	Obligatoire	Value	Description
   ID de base de données	Oui	<ID-base-de-données>	Base de données à laquelle vous souhaitez vous connecter.
   ID de conteneur	Oui	<ID-conteneur>	Conteneur que vous souhaitez interroger.
   Article	Oui	<JSON-document>	Document JSON que vous souhaitez créer. Cet exemple utilise le corps de la demande de la sortie du déclencheur. Conseil : si le jeton Body du déclencheur HTTP ne figure pas dans la liste de contenu dynamique à ajouter, en regard du nom du déclencheur, sélectionnez Afficher plus. Remarque : assurez-vous que le format JSON du corps est correct et qu’il contient au minimum la propriété id et la propriété de clé de partition pour votre document. Si un document avec l’id et la clé de partition spécifiés existe déjà, le document est mis à jour. Sinon, un nouveau document est créé.
   Clé de partition	Non	<partition-key>	Valeur de clé de partition pour le document que vous souhaitez créer.

   L’illustration suivante montre un exemple d’action :

   

8. Configurez tous les autres paramètres d’action en fonction des besoins.

9. Dans la barre d’outils du Concepteur, sélectionnez Enregistrer.

10. Testez votre application logique pour vous assurer que votre flux de travail crée un document dans le conteneur spécifié.

Se connecter à Azure Cosmos DB

Lorsque vous ajoutez un déclencheur ou une action qui se connecte à un service ou à un système et que vous n’avez pas de connexion existante ou active, Azure Logic Apps vous invite à fournir les informations de connexion, qui varient selon le type de connexion, par exemple :

• Vos informations d’identification de votre compte
• Un nom à utiliser pour la connexion
• Le nom pour le serveur ou le système
• Type d’authentification à utiliser
• Une chaîne de connexion

Pour pouvoir configurer votre déclencheur Azure Cosmos DB ou votre action Azure Cosmos DB, vous devez vous connecter à un compte de base de données.

Consommation

Dans un flux de travail d’application logique (Consommation), une connexion Azure Cosmos DB requiert les valeurs de propriétés suivantes :

Propriété	Obligatoire	Value	Description
Nom de connexion	Oui	<connection-name>	Nom à utiliser pour votre connexion.
Type d’authentification	Oui	<type-connexion>	Le type d’authentification que vous souhaitez utiliser. Cet exemple utilise une Clé d’accès. - Si vous sélectionnez Clé d’accès, spécifiez les autres valeurs de propriétés requises pour créer la connexion. - Si vous sélectionnez Microsoft Entra intégré, aucune autre valeur de propriété n’est requise, mais vous devez configurer votre connexion en suivant les étapes de l’authentification Microsoft Entra et du connecteur Azure Cosmos DB.
Clé d'accès à votre compte Azure Cosmos DB	Oui	<access-key>	Clé d’accès pour le compte Azure Cosmos DB à utiliser pour cette connexion. Cette valeur est soit une clé en lecture-écriture, soit une clé en lecture seule. Remarque : pour trouver la clé, accédez à la page du compte Azure Cosmos DB. Dans le menu de navigation, sous Paramètres, sélectionnez Identité. Copiez l’une des valeurs de clé disponibles.
ID de compte	Oui	<account-ID>	Nom du compte Azure Cosmos DB à utiliser pour cette connexion.

L’illustration suivante montre un exemple de connexion :

Remarque

Si, après avoir créé votre connexion, vous souhaitez utiliser une autre connexion Azure Cosmos DB existante ou créer une connexion, sélectionnez Modifier la connexion dans l’éditeur des informations relatives au déclencheur ou à l’action.

Standard

Dans un flux de travail d’application logique (Standard), une connexion Azure Cosmos DB requiert les valeurs de propriétés suivantes :

Propriété	Obligatoire	Value	Description
Nom de connexion	Oui	<connection-name>	Nom à utiliser pour votre connexion.
Chaîne de connexion	Oui	<connection-string>	Chaîne de connexion Azure Cosmos DB à utiliser pour votre connexion. Remarque : pour trouver la chaîne de connexion, accédez à la page du compte Azure Cosmos DB. Dans le menu de navigation, sous Paramètres, sélectionnez Identité. Copiez l’une des valeurs de chaîne de connexion disponibles.

L’illustration suivante montre un exemple de connexion :

Remarque

Si, après avoir créé votre connexion, vous souhaitez utiliser une autre connexion Azure Cosmos DB existante ou créer une connexion, sélectionnez Modifier la connexion dans l’éditeur des informations relatives au déclencheur ou à l’action.

Référence sur les connecteurs

Pour accéder à des informations de référence sur les opérations de connecteur managé Azure Cosmos DB, par exemple, sur les déclencheurs, les actions et les limites, consultez la page de référence du connecteur.

Il n’existe aucune page de référence correspondante pour les opérations Azure Cosmos DB intégrées. Au lieu de cela, consultez le tableau suivant pour plus d’informations :

Type	Nom	Paramètres
Déclencheur	Lorsqu’un élément est créé ou modifié	- ID de base de données : obligatoire. Nom de la base de données avec les conteneurs surveillés et de bail. - ID de conteneur monitoré : obligatoire. Nom du conteneur surveillé. - ID de conteneur de baux : obligatoire. Nom du conteneur utilisé pour stocker les baux. - Créer un conteneur de baux : obligatoire. Si la valeur est true, créez le conteneur de baux s’il n’existe pas. - Débit du conteneur de baux : facultatif. Nombre d’unités de requête à attribuer lors de la création du conteneur de baux.
Action	Créer ou mettre à jour un élément	- ID de base de données : obligatoire. Nom de la base de données. - ID de conteneur : obligatoire. nom du conteneur. - Élément : obligatoire. Élément à créer ou à mettre à jour. - Clé de partition : facultative. Valeur de clé de partition pour l’élément demandé. - Est upsert : facultatif. Si la valeur est true, remplacez l’élément s’il existe. Dans le cas contraire, créez-le.
Action	Créer ou mettre à jour un grand nombre d’éléments en bloc	Cette action est optimisée pour les scénarios à débit élevé, et implique un traitement supplémentaire avant l’envoi de vos éléments à créer dans le conteneur Azure Cosmos DB. Pour un grand nombre d’éléments, ce traitement supplémentaire accélère l’exécution de la requête. Pour un petit nombre d’éléments, cette surcharge peut ralentir les performances par rapport à l’utilisation de plusieurs actions de création d’élément. - ID de base de données : obligatoire. Nom de la base de données. - ID de conteneur : obligatoire. nom du conteneur. - Éléments : obligatoire. Tableau d’éléments à créer ou à mettre à jour. - Est upsert : facultatif. Si la valeur est true, remplacez un élément s’il existe. Dans le cas contraire, créez-le.
Action	Lire un élément	- ID de base de données : obligatoire. Nom de la base de données. - ID de conteneur : obligatoire. nom du conteneur. - ID d’élément : obligatoire. Valeur id de l’élément demandé. - Clé de partition : obligatoire. Valeur de clé de partition pour l’élément demandé.
Action	Supprimer un élément	- ID de base de données : obligatoire. Nom de la base de données. - ID de conteneur : obligatoire. nom du conteneur. - ID d’élément : obligatoire. Valeur id de l’élément demandé. - Clé de partition : obligatoire. Valeur de clé de partition pour l’élément demandé.
Action	Éléments de requête	- ID de base de données : obligatoire. Nom de la base de données. - ID de conteneur : obligatoire. nom du conteneur. - Requête SQL : obligatoire. Texte de la requête SQL Azure Cosmos DB. - Clé de partition : facultative. Valeur de clé de partition pour la requête, le cas échéant. - Jeton de continuation : facultatif. Jeton de continuation pour cette requête, attribué par le service Azure Cosmos DB, le cas échéant. - Nombre maximal d’éléments : facultatif. Nombre maximal d’éléments que la requête peut retourner.

Meilleures pratiques pour les opérations intégrées Azure Cosmos DB

Obtenir des résultats itérables à partir de l’action Interroger les éléments

L’action intégrée Interroger les éléments d’un workflow Application logique (standard) comprend de nombreuses sorties de contenu dynamique qui peuvent être utilisées dans les actions suivantes. Pour obtenir les éléments des résultats de la requête ou les métadonnées des éléments sous la forme d’un objet itérable, effectuez les étapes suivantes :

1. Sur le Portail Azure, ouvrez votre flux de travail dans le Concepteur.

2. Si votre flux de travail est vide, ajoutez le déclencheur de votre choix.

   Cet exemple commence avec le déclencheur Récurrence.

3. Sous le déclencheur ou l’action à laquelle vous souhaitez ajouter l’action Azure Cosmos DB, sélectionnez Insérer une nouvelle étape (+) >Ajouter une action.

4. Dans le Concepteur, vérifiez que l’option Ajouter une opération est sélectionnée. Dans le volet Ajouter une action qui s’ouvre, sous la zone de recherche Choisir une opération, sélectionnez Intégré pour trouver les actions Azure Cosmos DB.

5. Dans la zone de recherche, entrez Azure Cosmos DB. Sélectionnez l’action Interroger les éléments (préversion).

6. Si vous êtes invité à entrer les informations de connexion, créez une connexion à votre compte Azure Cosmos DB.

7. Entrez les informations nécessaires pour l’action.

   Propriétés	Requis	Value	Description
   ID de base de données	Oui	<ID-base-de-données>	Base de données à laquelle vous souhaitez vous connecter.
   ID de conteneur	Oui	<ID-conteneur>	Conteneur que vous souhaitez interroger.
   Requête SQL	Oui	<sql-query>	Requête SQL pour votre demande.

   L’illustration suivante montre un exemple d’action :

   

8. Configurez tous les autres paramètres d’action en fonction des besoins.

9. Sous l’action, sélectionnez Insérer une nouvelle étape (+) >Ajouter une action. Dans le volet Ajouter une action qui s’ouvre, sélectionnez l’action que vous souhaitez exécuter sur tous les éléments de résultat de la requête.

Cet exemple utilise l’action intégrée Azure Cosmos DB nommée Supprimer un élément (préversion).

1. Dans l’action que vous avez ajoutée précédemment, vous pouvez accéder aux données de la sortie de requête. Cliquez dans l’un des champs d’entrée de cette action pour afficher la liste de contenu dynamique. Sélectionnez l’un des éléments de réponse disponibles ou sélectionnez Afficher plus pour voir plus d’options.

Cet exemple utilise l’ID d’élément de réponse dans le champ ID de l’élément pour renseigner les ID en fonction des résultats de la requête.

1. Une fois que vous avez sélectionné un élément de réponse, l’action For each est automatiquement ajoutée pour itérer au sein de tous les résultats de la requête. La boucle For each contient l’action que vous avez ajoutée précédemment. Vous pouvez ajouter toutes les autres actions souhaitées à votre boucle.

2. Dans la barre d’outils du Concepteur, sélectionnez Enregistrer.

3. Testez votre application logique pour vous assurer que votre flux de travail retourne la sortie attendue.

Étapes suivantes

• Connecteurs managés pour Azure Logic Apps
• Connecteurs intégrés pour Azure Logic Apps
• Qu’est-ce que des connecteurs dans Azure Logic Apps