Champs d’ID dans Bot Framework

  • Article

S’APPLIQUE À : SDK v4

Ce guide décrit les caractéristiques des champs d’ID dans Bot Framework.

ID du canal

Chaque canal de Bot Framework est identifié par un ID unique.

Exemple : "channelId": "slack"

Les ID de canal font office d’espaces de noms pour d’autres ID. Les appels de runtime dans le protocole Bot Framework doivent intervenir dans le contexte d’un canal. Le canal donne un sens à la conversation et aux identifiants de compte utilisés lors de la communication.

Par convention, tous les ID de canal sont en minuscules. Les canaux garantissent que les ID de canal qu’ils émettent ont une casse cohérente, et que les bots peuvent donc utiliser des comparaisons ordinales pour établir des équivalences.

Règles pour les ID de canal

  • Les ID sont sensibles à la casse.

Descripteur de bot

Chaque bot qui a été inscrit auprès d’Azure AI Bot Service a un descripteur de bot.

Exemple : FooBot

Un descripteur de bot représente l’inscription d’un bot auprès du service en ligne Azure AI Bot Service. Cette inscription est associée à un point de terminaison de webhook HTTP et à des inscriptions auprès de canaux.

Azure AI Bot Service garantit l’unicité des descripteurs de bot. Le portail Azure effectue une vérification de l’unicité ne tenant pas compte de la casse (ce qui signifie que les variations de casse d’un descripteur de bot sont traitées comme un même descripteur), bien qu’il s’agisse d’une caractéristique du portail Azure, et pas nécessairement du descripteur de bot proprement dit.

Règles pour les descripteurs de bot

  • Les descripteurs de bot sont uniques (sans tenir compte de la casse) au sein du Bot Framework.

ID d’application

Chaque bot qui a été inscrit auprès d’Azure AI Bot Service a un ID d’application.

Remarque

Les applications étaient précédemment mentionnées sous le nom « Applications MSA » ou « Applications MSA/AAD ». Les applications sont désormais plus généralement appelées simplement « applications », mais il se peut que certains éléments de protocole continuent à faire référence aux applications en tant qu’« Applications MSA » à perpétuité.

Exemple : "msaAppId": "353826a6-4557-45f8-8d88-6aa0526b8f77"

Une application représente une inscription auprès du portail d’application de l’équipe Identité, et sert de mécanisme d’identité de service à service dans le protocole de runtime de Bot Framework. Les applications peuvent avoir des associations autres que de bots, tels que des sites Web et des applications mobiles ou de bureau.

Chaque bot inscrit a exactement une application. Bien qu’il soit impossible pour le propriétaire d’un bot de modifier de façon indépendante l’application associée à son bot, l’équipe Bot Framework peut faire cela dans quelques cas exceptionnels.

Les bots et les canaux peuvent utiliser des ID d’application pour identifier de façon unique des robots inscrits.

Il est garanti que les ID d’application sont des GUID. Les ID d’application doivent être comparés sans respect de la casse.

Règles pour les ID d’application

  • Les ID d’application sont uniques (comparaison de GUID) au sein de la plateforme d’application Microsoft.
  • Chaque bot a exactement une application correspondante.
  • La modification de l’application à laquelle un bot est associé nécessite l’assistance de l’équipe Bot Framework.

Compte de canal

Chaque bot et utilisateur a un compte au sein de chaque canal. Le compte contient un identificateur (id) et d’autres données non structurelles informatives sur bot, en tant que nom facultatif.

Exemple : "from": { "id": "john.doe@contoso.com", "name": "John Doe" }

Ce compte décrit l’adresse à l’intérieur du canal dans lequel des messages peuvent être envoyés et reçus. Dans certains cas, ces inscriptions existent au sein d’un seul service, comme exemple, Facebook. Dans d’autres cas, elles existent dans de nombreux systèmes (adresses e-mail, numéros de téléphone). Dans des canaux plus anonymes, comme Chat Web, l’inscription peut être éphémère.

Les comptes de canal sont imbriqués dans des canaux. Un compte Facebook, par exemple, n’est qu’un nombre. Ce nombre peut avoir une signification différente dans d’autres canaux, et n’a aucune signification en dehors des canaux.

La relation entre des comptes de canal et des utilisateurs (personnes réelles) dépend des conventions associées à chaque canal. Par exemple, un numéro de SMS fait généralement référence à une personne, mais le numéro peut être transféré à quelqu’un d’autre. Inversement, un compte Facebook fait généralement référence à une personne à perpétuité, même s’il n’est pas rare que deux personnes partagent un même compte Facebook.

Dans la plupart des canaux, il convient de considérer un compte de canal comme une sorte de boîte aux lettres à laquelle des messages peuvent être remis. La plupart des canaux autorisent généralement le mappage de plusieurs adresses à une boîte aux lettres unique. Par exemple, « jdoe@contoso.com » et « john.doe@service.contoso.com » peuvent être résolus dans la même boîte de réception. Certains canaux vont plus loin et modifient l’adresse du compte en fonction du bot qui y accède. Par exemple, Facebook modifie les identifiants utilisateur afin que chaque bot ait une adresse différente pour l’envoi et la réception de messages.

Bien qu’il soit possible dans certains cas d’établir une équivalence entre des adresses, l’établissement d’une équivalence entre des boîtes aux lettres ainsi qu’entre des personnes nécessite une connaissance des conventions au sein du canal, ce qui, dans de nombreux cas, n’est pas possible.

Un bot est informé de son adresse de compte de canal via le champ recipient sur les activités qui lui sont envoyées.

Règles pour les comptes de canal

  • Les comptes de canal n’ont de signification qu’au sein du canal qui leur est associé.
  • Plusieurs ID peuvent correspondre au même compte.
  • Une comparaison ordinale permet d’établir que deux ID sont identiques.
  • Il n’existe généralement pas de comparaison utilisable pour déterminer si deux ID distincts correspondent au même compte, au même bot ou à la même personne.
  • La stabilité des associations entre des ID, comptes, boîtes aux lettres et personnes dépend du canal.

ID de conversation

Des messages sont envoyés et reçus dans le contexte d’une conversation identifiable par un ID.

Exemple : "conversation": { "id": "1234" }

Une conversation contient un échange de messages et d’autres activités. Chaque conversation comporte zéro ou plusieurs activités, et chaque activité n’apparaît que dans une seule conversation. Des conversations peuvent être perpétuelles, ou avoir des débuts et des fins distinctes. Le processus de création, de modification ou de terminaison d’une conversation se produit à l’intérieur du canal (une conversation existe quand le canal en est informé) et les caractéristiques de ces processus sont établies par le canal.

Les activités au sein d’une conversation sont envoyées par des utilisateurs et des bots. La définition des utilisateurs qui « participent » à une conversation varie selon le canal, et peut inclure théoriquement des utilisateurs présents, des utilisateurs qui ont reçu un message, et des utilisateurs qui ont envoyé un message.

Quelques canaux comme SMS, voire d’autres, présentent la singularité que l’ID de conversation affecté à une conversation de 1 à 1 est l’ID de compte du canal distant. Cette singularité a deux effets secondaires :

  1. L’ID de conversation est subjectif selon la personne qui le considère. Si des participants A et B discutent, le participant A voit l’ID de conversation « B », et le participant B l’ID de conversation « A ».
  2. Si le bot compte plusieurs comptes de canal au sein de ce canal (par exemple, si le robot a deux numéros de SMS), l’ID de conversation n’est pas suffisant pour identifier de manière unique la conversation dans le champ de vision du bot.

Par conséquent, un ID de conversation n’identifie pas nécessairement de manière unique une conversation au sein d’un canal, même pour un seul bot.

Règles pour les ID de conversation

  • Les conversations n’ont de signification qu’au sein du canal qui leur est associé.
  • Plusieurs ID peut correspondre à une même conversation.
  • L’égalité ordinale n’établit pas nécessairement que deux ID de conversation correspondent à la même conversation, même si c’est le plus souvent le cas.

ID d’activité

Des activités sont envoyées et reçues dans le protocole Bot Framework, et elles sont parfois identifiables.

Exemple : "id": "5678"

Les ID d’activité sont facultatifs et utilisés par les canaux pour donner au bot un moyen de référencer l’ID dans des appels d’API subséquents, s’ils sont disponibles :

  • Réponse à une activité particulière
  • Interrogation de la liste des participants au niveau d’une activité

Aucun autre cas d’utilisation n’étant établi, il n’existe pas d’autres règles pour le traitement des ID d’activité.