Champs d’ID dans Bot FrameworkID fields in the Bot Framework

s’applique à : SDK v4APPLIES TO: SDK v4

Ce guide décrit les caractéristiques des champs d’ID dans Bot Framework.This guide describes the characteristics of ID fields in the Bot Framework.

ID de canalChannel ID

Chaque canal de Bot Framework est identifié par un ID unique.Every Bot Framework channel is identified by a unique ID.

Exemple : "channelId": "slack"Example: "channelId": "slack"

Les ID de canal font office d’espaces de noms pour d’autres ID.Channel IDs serve as namespaces for other IDs. 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.Runtime calls in the Bot Framework protocol must take place within the context of a channel; the channel gives meaning to the conversation and account IDs used when communicating.

Par convention, tous les ID de canal sont en minuscules.By convention all channel IDs are lowercase. Les canaux garantissent que les ID de canal qu’ils émettent ont une casse cohérente, et que les robots peuvent donc utiliser des comparaisons ordinales pour établir des équivalences.Channels guarantee that the channel IDs they emit have consistent casing, and thus bots may use ordinal comparisons to establish equivalence.

Règles pour les ID de canalRules for channel IDs

  • Les ID sont sensibles à la casse.Channel IDs are case-sensitive.

Descripteur de robotBot Handle

Chaque bot qui a été inscrit auprès d’Azure Bot Service a un descripteur de bot.Every bot that has been registered with the Azure Bot Service has a bot handle.

Exemple : FooBotExample: FooBot

Un descripteur de bot représente l’inscription d’un bot auprès du service en ligne Azure Bot Service.A bot handle represents a bot's registration with the online Azure Bot Service. Cette inscription est associée à un point de terminaison de webhook HTTP et à des inscriptions auprès de canaux.This registration is associated with an HTTP webhook endpoint and registrations with channels.

Azure Bot Service garantit l’unicité des descripteurs de bot.The Azure Bot Service ensures uniqueness of bot handles. 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.The Azure portal performs a case-insensitive uniqueness check (meaning that case variations of bot handle are treated as a single handle) although this is a characteristic of the Azure portal, and not necessarily the bot handle itself.

Règles pour les descripteurs de robotRules for bot handles

  • Les descripteurs de robot sont uniques (sans tenir compte de la casse) au sein du Bot Framework.Bot handles are unique (case-insensitive) within the Bot Framework.

ID d'applicationApp ID

Chaque bot qui a été inscrit auprès d’Azure Bot Service a un ID d’application.Every bot that has been registered with the Azure Bot Service has an App ID.

Notes

Auparavant, les applications étaient communément appelées « Applications MSA » ou « Applications MSA/AAD ».Previously, apps were commonly referred to as "MSA Apps" or "MSA/AAD Apps." 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é.Apps are now more commonly referred to simply as "apps", but some protocol elements may refer to apps as "MSA Apps" in perpetuity.

Exemple : "msaAppId": "353826a6-4557-45f8-8d88-6aa0526b8f77"Example: "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.An app represents a registration with the Identity team's App portal, and serves as the service-to-service identity mechanism within the Bot Framework runtime protocol. Les applications peuvent avoir des associations autres que de robots, tels que des sites web et des applications mobiles ou de bureau.Apps may have other non-bot associations, such as websites and mobile/desktop applications.

Chaque robot inscrit a exactement une application.Every registered bot has exactly one app. Bien qu’il soit impossible pour le propriétaire d’un robot de modifier de façon indépendante l’application associée à son robot, l’équipe Bot Framework peut faire cela dans un petit nombre de cas exceptionnels.Although it's not possible for a bot owner to independently change which app is associated with their bot, the Bot Framework team can do so in a small number of exceptional cases.

Les robots et les canaux peuvent utiliser des ID d’application pour identifier de façon unique des robots inscrits.Bots and channels may use app IDs to uniquely identify a registered bot.

Il est garanti que les ID d’application sont des GUID.App IDs are guaranteed to be GUIDs. Les ID d’application doivent être comparés sans respect de la casse.App IDs should be compared without case sensitivity.

Règles pour les ID d’applicationRules for app IDs

  • Les ID d’application sont uniques (comparaison de GUID) au sein de la plateforme d’application Microsoft.App IDs are unique (GUID comparison) within the Microsoft App platform.
  • Chaque robot a exactement une application correspondante.Every bot has exactly one corresponding app.
  • La modification de l’application à laquelle un robot est associé nécessite l’assistance de l’équipe Bot Framework.Changing which app a bot is associated with requires the assistance of the Bot Framework team.

Compte de canalChannel Account

Chaque robot et utilisateur a un compte au sein de chaque canal.Every bot and user has an account within each channel. Le compte contient un identificateur (id) et d’autres données non structurelles informatives sur robot, en tant que nom facultatif.The account contains an identifier (id) and other informative bot non-structural data, like an optional name.

Exemple : "from": { "id": "john.doe@contoso.com", "name": "John Doe" }Example: "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.This account describes the address within the channel where messages may be sent and received. Dans certains cas, ces inscriptions existent au sein d’un seul service (par exemple, Facebook).In some cases, these registrations exist within a single service (e.g., Facebook). Dans d’autres cas, elles existent dans de nombreux systèmes (adresses e-mail, numéros de téléphone).In others, they are registered across many systems (email addresses, phone numbers). Dans des canaux plus anonymes (par exemple, Discussion Web), l’inscription peut être éphémère.In more anonymous channels (e.g., Web Chat), the registration may be ephemeral.

Les comptes de canal sont imbriqués dans des canaux.Channel accounts are nested within channels. Un compte Facebook, par exemple, n’est qu’un nombre.A Facebook account, for example, is simply a number. Ce nombre peut avoir une signification différente dans d’autres canaux, et n’a aucune signification en dehors des canaux.This number may have a different meaning in other channels, and it doesn't have meaning outside all channels.

La relation entre des comptes de canal et des utilisateurs (personnes réelles) dépend des conventions associées à chaque canal.The relationship between channel accounts and users (actual people) depends on conventions associated with each channel. Par exemple, un numéro de SMS fait généralement référence à une personne pendant une période de temps à l’issue de laquelle le numéro peut être transféré à quelqu’un d’autre.For example, an SMS number typically refers to one person for a period of time, after which the number may be transferred to someone else. 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.Conversely, a Facebook account typically refers to one person in perpetuity, although it is not uncommon for two people to share a Facebook account.

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.In most channels, it's appropriate to think of a channel account as a kind of mailbox where messages can be delivered. 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 correspondre à la même boîte de réception.It's typical for most channels to allow multiple address to map to a single mailbox; for example, "jdoe@contoso.com" and "john.doe@service.contoso.com" may resolve to the same inbox. Certains canaux vont plus loin en modifiant l’adresse du compte en fonction du bot qui y accède. Par exemple, Facebook modifie les ID utilisateur de façon à ce que chaque bot ait une adresse distincte pour l’envoi et la réception de messages.Some channels go a step further and alter the account's address based on which bot is accessing it; for example, Facebook alters user IDs so every bot has a different address for sending and receiving 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.While it's possible in some cases to establish equivalency between addresses, establishing equivalency between mailboxes and equivalency between people requires knowledge of the conventions within the channel, and is in many cases not possible.

Un robot est informé de son adresse de compte de canal via le champ recipient sur les activités qui lui sont envoyées.A bot is informed of its channel account address via the recipient field on activities sent to the bot.

Règles pour les comptes de canalRules for channel accounts

  • Les comptes de canal n’ont de signification qu’au sein du canal qui leur est associé.Channel accounts have meaning only within their associated channel.
  • Plusieurs ID peuvent correspondre au même compte.More than one ID may resolve to the same account.
  • Une comparaison ordinale permet d’établir que deux ID sont identiques.Ordinal comparison may be used to establish that two IDs are the same.
  • 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 robot ou à la même personne.There is generally no comparison that can be used to identify whether two different IDs resolve to the same account, bot or person.
  • La stabilité des associations entre des ID, comptes, boîtes aux lettres et personnes dépend du canal.The stability of associations between IDs, accounts, mailboxes, and people depends on the channel.

ID de conversationConversation ID

Des messages sont envoyés et reçus dans le contexte d’une conversation identifiable par un ID.Messages are sent and received in the context of a conversation, which is identifiable by ID.

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

Une conversation contient un échange de messages et d’autres activités.A conversation contains an exchange of messages and other activities. Chaque conversation comporte zéro ou plusieurs activités, et chaque activité n’apparaît que dans une seule conversation.Every conversation has zero or more activities, and every activity appears in exactly one conversation. Des conversations peuvent être perpétuelles, ou avoir des débuts et des fins distinctes.Conversations may be perpetual, or may have distinct starts and ends. Le processus de création, de modification ou de terminaison d’une conversation se produit à l’intérieur du canal (c’est-à-dire qu’une conversation existe quand le canal en est informé) et les caractéristiques de ces processus sont établies par le canal.The process of creating, modifying, or ending a conversation occurs within the channel (i.e., a conversation exists when the channel is aware of it) and the characteristics of these processes are established by the channel.

Les activités au sein d’une conversation sont envoyées par des utilisateurs et des robots.The activities within a conversation are sent by users and 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.The definition for which users "participate" in a conversation varies by channel, and can theoretically include present users, users who have ever received a message, users who sent a 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.Several channels (e.g., SMS, and possibly others) have the quirk that the conversation ID assigned to a 1:1 conversation is the remote channel account ID. Cette singularité a deux effets secondaires :This quirk has two side-effects:

  1. L’ID de conversation est subjectif selon la personne qui le considère.The conversation ID is subjective based on who is viewing it. 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 ».If Participants A and B are talking, participant A sees the conversation ID to be "B" and participant B sees the conversation ID to be "A."
  2. Si le robot 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.If the bot has multiple channel accounts within this channel (for example, if the bot has two SMS numbers), the conversation ID is not sufficient to uniquely identify the conversation within the bot's field of view.

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 robot.Thus, a conversation ID does not necessarily uniquely identify a single conversation within a channel even for a single bot.

Règles pour les ID de conversationRules for conversation IDs

  • Les conversations n’ont de signification qu’au sein du canal qui leur est associé.Conversations have meaning only within their associated channel.
  • Plusieurs ID peut correspondre à une même conversation.More than one ID may resolve to the same 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.Ordinal equality does not necessarily establish that two conversation IDs are the same conversation, although in most cases, it does.

ID d’activitéActivity ID

Des activités sont envoyées et reçues dans le protocole Bot Framework, et elles sont parfois identifiables.Activities are sent and received within the Bot Framework protocol, and these are sometimes identifiable.

Exemple : "id": "5678"Example: "id": "5678"

Les ID d’activité sont facultatifs et utilisés par les canaux pour donner au robot un moyen référencer l’ID dans des appels d’API subséquents, s’ils sont disponibles :Activity IDs are optional and employed by channels to give the bot a way to reference the ID in subsequent API calls, if they are available:

  • Réponse à une activité particulièreReplying to a particular activity
  • Interrogation de la liste des participants au niveau d’une activitéQuerying for the list of participants at the activity level

Aucun autre cas d’utilisation n’étant établi, il n’existe pas d’autres règles pour le traitement des ID d’activité.Because no further use cases have been established, there are no additional rules for the treatment of activity IDs.