Champs d’ID dans Bot Framework

S’APPLIQUE À : SDK v4

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

ID de canal

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

Exemple : "channelId": "slack"

Les ID de canal servent d’espaces de noms pour d’autres ID. Les appels d’exécution dans le protocole Bot Framework doivent avoir lieu dans le contexte d’un canal ; le canal donne une signification aux ID de conversation et 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 donc les bots peuvent utiliser des comparaisons ordinales pour établir l’équivalence.

Règles pour les ID de canal

• Les ID de canal respectent la casse.

Bot Handle

Chaque bot inscrit auprès d’Azure AI Bot Service dispose d’un handle de bot.

Exemple : FooBot

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

Azure AI Bot Service garantit l’unicité des handles de bot. Le portail Azure effectue un contrôle d’unicité qui ne respecte pas la casse (ce qui signifie que les variantes de cas de handle de bot sont traitées comme un handle unique), bien qu’il s’agit d’une caractéristique du portail Azure, et pas nécessairement du handle de bot lui-même.

Règles pour les handles de bot

• Les handles de bot sont uniques (sans respect de la casse) dans Bot Framework.

ID d’application

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

Exemple : "msaAppId": "00001111-aaaa-2222-bbbb-3333cccc4444"

Une application représente une inscription auprès du portail d’application de l’équipe d’identité et sert de mécanisme d’identité de service à service dans le protocole d’exécution Bot Framework. Les applications peuvent avoir d’autres associations non bot, telles que des sites web et des applications mobiles/de bureau.

Chaque bot inscrit a exactement une application. Bien qu’il ne soit pas possible qu’un propriétaire de bot change indépendamment l’application associée à son bot, l’équipe Bot Framework peut le faire dans quelques cas exceptionnels.

Les bots et les canaux peuvent utiliser des ID d’application pour identifier de manière unique un bot inscrit.

Les ID d’application sont garantis comme 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 GUID) au sein de la plateforme Microsoft App.
• Chaque bot a exactement une application correspondante.
• La modification de l’application associée à un bot nécessite l’aide de l’équipe Bot Framework.

Compte de canal

Chaque bot et utilisateur dispose d’un compte au sein de chaque canal. Le compte contient un identificateur (id) et d’autres données non structurelles de bot d’information, comme un nom facultatif.

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

Ce compte décrit l’adresse dans le canal où les messages peuvent être envoyés et reçus. Dans certains cas, ces inscriptions existent au sein d’un seul service, tel que Facebook. Dans d’autres, ils sont inscrits sur de nombreux systèmes (adresses e-mail, numéros de téléphone). Dans d’autres canaux anonymes, tels que Web Chat, l’inscription peut être éphémère.

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

La relation entre les comptes de canal et les utilisateurs (personnes réelles) dépend des conventions associées à chaque canal. Par exemple, un numéro SMS fait généralement référence à une personne, mais le nombre peut être transféré à quelqu’un d’autre. À l’inverse, 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 compte Facebook.

Dans la plupart des canaux, il est approprié de considérer un compte de canal comme un type de boîte aux lettres où les messages peuvent être remis. Il est courant que la plupart des canaux autorisent plusieurs adresses à mapper à 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 de laquelle le bot y accède. Par exemple, Facebook modifie les ID 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 l’équivalence entre les adresses, l’établissement d’une équivalence entre les boîtes aux lettres et l’équivalence entre les personnes nécessite une connaissance des conventions au sein du canal et n’est pas possible dans de nombreux cas.

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

Règles pour les comptes de canal

• Les comptes de canal ont une signification uniquement dans leur canal associé.
• Plusieurs ID peuvent être résolus sur le même compte.
• La comparaison ordinale peut être utilisée pour établir que deux ID sont identiques.
• Il n’existe généralement aucune comparaison qui peut être utilisée pour identifier si deux ID différents sont résolus sur le même compte, bot ou personne.
• La stabilité des associations entre ID, comptes, boîtes aux lettres et personnes dépend du canal.

Conversation ID

Les messages sont envoyés et reçus dans le contexte d’une conversation, qui est identifiable par ID.

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

Une conversation contient un échange de messages et d’autres activités. Chaque conversation a zéro ou plusieurs activités, et chaque activité apparaît exactement dans une conversation. Les conversations peuvent être perpétuelles ou peuvent avoir des démarrages et des fins distincts. Le processus de création, de modification ou de fin d’une conversation se produit dans le canal ( une conversation existe uniquement pendant que le canal est conscient de celui-ci) et les caractéristiques de ces processus sont établies par le canal.

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

Plusieurs canaux, tels que SMS, et éventuellement d’autres, ont la bizarre que l’ID de conversation affecté à une conversation 1:1 est l’ID de compte de canal distant. Ce quirk a deux effets secondaires :

1. L’ID de conversation est subjectif, en fonction de qui l’affiche. Si les participants A et B parlent, le participant A voit l’ID de conversation « B » et le participant B voit l’ID de conversation « A ».
2. Si le bot a plusieurs comptes de canal au sein de ce canal (par exemple, si le bot a deux numéros SMS), l’ID de conversation n’est pas suffisant pour identifier de manière unique la conversation dans le champ d’affichage du bot.

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

Règles pour les ID de conversation

• Les conversations ont une signification uniquement dans leur canal associé.
• Plusieurs ID peuvent être résolus dans la même conversation.
• L’égalité ordinale n’établit pas nécessairement que deux ID de conversation sont la même conversation, bien que dans la plupart des cas, elle le fasse.

ID d’activité

Les 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 permettre au bot de référencer l’ID dans les appels d’API suivants, s’ils sont disponibles :

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

Étant donné qu’aucun cas d’usage supplémentaire n’a été établi, il n’existe aucune règle supplémentaire pour le traitement des ID d’activité.