Découvrir les meilleures pratiques pour les champs de chaîne

L’article suivant contient des conseils généraux relatifs aux champs de chaîne d’un connecteur pour Power Automate, Power Apps et Azure Logic Apps.

Informations sur le connecteur

Chaque connecteur doit avoir un titre, qui est le nom du connecteur, et une description, qui décrit le connecteur en général. Ces informations doivent être spécifiées dans les champs title (intitulé) et description sous la section info de la définition OpenAPI (dans le fichier apiDefinition.swagger.json).

Les instructions suivantes doivent être respectées au minimum pour les intitulés et les descriptions du connecteur :

• L’intitulé du connecteur peut comprendre jusqu’à 30 caractères au maximum.
• L’intitulé et la description du connecteur ne peuvent pas inclure le mot API.
• L’intitulé et la description du connecteur ne doivent pas faire référence à un produit Power Platform, ni à un produit pour lequel vous ne possédez pas les API back-end.

Vous trouverez ici une version plus stricte des instructions relatives aux champs de l’intitulé et de la description appliquées aux connecteurs certifiés. Ces instructions sont à utiliser comme meilleures pratiques.

Opérations

Chaque chemin d’accès et verbe de la définition OpenAPI correspond à une opération. Bien décrire l’opération avec toutes les chaînes/balises ci-dessous aide l’utilisateur final à l’utiliser correctement. Certains des champs de chaîne pour une opération sont :

• summary  : Cela apparaîtra comme le nom de l’opération.

  • Incident : phrase
  • Remarques :
    • Il ne devrait pas y avoir de barre oblique (« / ») dans le nom.
    • Il ne peut pas contenir plus de 80 caractères.
    • Le nom ne doit pas se terminer par un caractère non alphanumérique, notamment de la ponctuation ou un espace.

• description  : cela s’affichera comme description de l’opération lors de la sélection du bouton d’information , comme illustré dans l'image suivante.

  • Casse : Phrase.
  • Remarques : Restez bref pour tenir dans la zone de texte. Aucun point requis en cas d’un seul mot.

• operationId  : il s’agit de l’ID unique associé à l’opération.

  • Casse : Camel (pas d'espaces ni de ponctuation).
  • Remarques : cet élément est destiné à transmettre le sens de l’opération comme GetContacts ou CreateContact.

  L’image suivante montre comment les champs summary—Envoyer un e-mail et description—Cette opération envoie un e-mail s'afficheront sur l’interface utilisateur lors de la création d’un flux de travail.

  

Comparaison des déclencheurs et des actions

Un déclencheur démarre un workflow ou un processus. Par exemple, « Démarrer un flux de travail tous les lundis à 3:00 », « Après la création d’un objet », etc.

Les champs de synthèse et de description de déclencheur doivent être lisibles par l’homme et avoir une signification sémantique. La synthèse du déclencheur est généralement au format : « Quand un __________________ ».

Exemple :

Déclencher	Synthèse
Créer	Lorsqu’une tâche est créée
Mise à jour	Lorsqu’une tâche est mise à jour
Supprimé(e)	Lorsqu’une tâche est supprimée

La description d’un déclencheur est généralement au format : « Cette opération se déclenche lorsque _______________ »

Exemple :

• Cette opération se déclenche lorsqu’une nouvelle tâche est ajoutée.

Une action est une tâche à effectuer au sein de votre flux de travail, par exemple « Envoyer un e-mail », « Mettre à jour une ligne », « Envoyer une notification », etc. Quelques exemples d’actions summary sont donnés ci-dessous :

Pour	Synthèse
Créer	Créer une tâche
Lu	Récupérer une tâche par ID
Mise à jour	Mettre à jour un objet
Supprimé(e)	Supprimer l’objet
Liste	Liste de tous les objets

Paramètres

Chaque opération (un déclencheur ou une action) dispose de paramètres fournis en tant qu’entrée par l’utilisateur. Certains des champs de chaîne importants pour un paramètre sont :

• x-ms-summary  : Cela apparaîtra comme le nom du paramètre.

  • Casse : Titre
  • Remarques : le nom est limité à 80 caractères

• description  : Cela apparaîtra comme la description des paramètres dans la zone de saisie.

  • Incident : phrase
  • Remarques : Restez court pour tenir dans la zone de texte. Aucun point requis en cas d’un seul mot.

  Dans l’image ci-dessous, le paramètre mis en surbrillance a « Subject » (Objet) comme valeur pour le champ x-ms-summary et « Specify the subject of the mail » (Spécifier l’objet de l’e-mail) pour description.

  

Response

Chaque opération a une réponse qui peut être utilisée par la suite en tant qu’entrée pour une opération ultérieure dans le flux de travail. Le schéma du résultat est composé de plusieurs propriétés. Certains des champs de chaîne importants pour chaque propriété sont :

• x-ms-summary  : Cela apparaîtra comme le nom de la propriété du résultat.

  • Casse : Titre
  • Remarques : utilisez un nom court.

• description  : Cela apparaîtra comme la description de la propriété de résultat.

  • Casse : Phrase
  • Remarques : doit être courte et concise, avec un point à la fin.

  Dans l’image ci-dessous, le schéma de résultat de l’opération « Déclencher manuellement un flux » s’affiche lorsque vous essayez d’ajouter du contenu dynamique dans l’une des opérations suivantes du workflow. Ici, « User email » (E-mail de l’utilisateur) correspond au champ x-ms-summary. Le texte en dessous correspond au champ description pour une propriété dans la réponse de l’opération « Manually trigger a flow » (Déclencher manuellement un flux).

Voici quelques remarques importantes concernant les champs summary/x-ms-summary et description à prendre en compte de manière générale :

• La synthèse et le texte de description ne doivent pas être identiques.
• La description doit servir à fournir des informations supplémentaires à l’utilisateur, notamment concernant le format de sortie ou l’objet associé à la propriété. Par exemple : summary : ID, description : ID d’utilisateur.
• Dans le cas d’un objet comprenant des valeurs imbriquées, le champ x-ms-summary du nom du parent sera ajouté à l’enfant.

x-ms-visibility

Détermine la priorité de visibilité de l’entité. Si aucune visibilité n’est spécifiée, la visibilité est traitée comme « normal ». Les valeurs « important », « avancé » et « interne » sont possibles. Les entités marquées comme internes ne s’affichent pas dans l’interface utilisateur.

S’applique à :

• Opérations
• Paramètres
• Propriétés de la réponse

Exemple :

Dans l’interface utilisateur, les entités marquées comme « important » sont généralement affichées en premier. Les éléments marqués comme « avancé » sont masqués sous un bouton bascule (mis en surbrillance) et ceux marqués comme « interne » ne sont pas affichés. L'image suivante est un exemple de paramètres marqués comme « important » affichés par défaut. Elle montre également les paramètres marqués comme « avancé » affichés après la sélection du bouton Afficher les options avancées.

Fournir des commentaires

Nous apprécions grandement les commentaires sur les problèmes liés à notre plateforme de connecteurs ou les idées de nouvelles fonctionnalités. Pour fournir des commentaires, accédez à Soumettre des problèmes ou obtenir de l’aide avec les connecteurs et sélectionnez votre type de commentaire.