Campos de identificador en Bot FrameworkID fields in the Bot Framework

se aplica a: SDK V4APPLIES TO: SDK v4

Esta guía describe las características de los campos de identificador en Bot Framework.This guide describes the characteristics of ID fields in the Bot Framework.

Channel IDChannel ID

Todos y cada uno de los canales de Bot Framework se identifican mediante un identificador único.Every Bot Framework channel is identified by a unique ID.

Ejemplo: "channelId": "slack"Example: "channelId": "slack"

Los identificadores de canal sirven como espacios de nombres para otros identificadores.Channel IDs serve as namespaces for other IDs. Las llamadas en tiempo de ejecución en el protocolo de Bot Framework tienen que producirse dentro del contexto de un canal; el canal proporciona significado a la conversación y a los identificadores de cuenta que se usan al comunicarse.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.

Por convención, todos los identificadores de canal están en minúsculas.By convention all channel IDs are lowercase. Los canales garantizan que los identificadores de canal que emiten mantienen coherencia en el uso de mayúsculas y minúsculas y, por lo tanto, los bots pueden usar comparaciones ordinales para establecer la equivalencia.Channels guarantee that the channel IDs they emit have consistent casing, and thus bots may use ordinal comparisons to establish equivalence.

Reglas para los identificadores de canalRules for channel IDs

  • Los identificadores distinguen entre mayúsculas y minúsculas.Channel IDs are case-sensitive.

Identificador de botBot Handle

Cada bot que se ha registrado con Azure Bot Service tiene un identificador de bot.Every bot that has been registered with the Azure Bot Service has a bot handle.

Ejemplo: FooBotExample: FooBot

El identificador de bot representa el registro de un bot con Azure Bot Service en línea.A bot handle represents a bot's registration with the online Azure Bot Service. Este registro se asocia con un punto de conexión de webhook HTTP y los registros de canales.This registration is associated with an HTTP webhook endpoint and registrations with channels.

Azure Bot Service garantiza la exclusividad de los identificadores de bot.The Azure Bot Service ensures uniqueness of bot handles. Azure Portal realiza una comprobación de la exclusividad de mayúsculas y minúsculas (lo que significa que las variaciones de mayúsculas y minúsculas del identificador de bot se tratan como un único identificador), aunque esto sea una característica de Azure Portal, y no necesariamente del propio identificador de bot.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.

Reglas para los identificadores de botRules for bot handles

  • Los identificadores de bot son únicos (mayúsculas y minúsculas) dentro de Bot Framework.Bot handles are unique (case-insensitive) within the Bot Framework.

Id. de aplicaciónApp ID

Cada bot que se ha registrado con Azure Bot Service tiene un identificador de aplicación.Every bot that has been registered with the Azure Bot Service has an App ID.

Nota

Anteriormente, las aplicaciones se conocían normalmente como "Aplicaciones de MSA" o "Aplicaciones de AAD/MSA".Previously, apps were commonly referred to as "MSA Apps" or "MSA/AAD Apps." Ahora las aplicaciones se conocen normalmente solo como "aplicaciones", pero algunos elementos de protocolo pueden seguir haciendo referencia a las aplicaciones como "Aplicaciones de MSA".Apps are now more commonly referred to simply as "apps", but some protocol elements may refer to apps as "MSA Apps" in perpetuity.

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

Una aplicación representa un registro con el portal de aplicaciones del equipo de identidad y sirve como mecanismo de identidad de servicio a servicio dentro del protocolo de tiempo de ejecución 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. Las aplicaciones pueden tener otras asociaciones que no sean de bot, como sitios web y aplicaciones de escritorio o móviles.Apps may have other non-bot associations, such as websites and mobile/desktop applications.

Cada bot registrado tiene exactamente una aplicación.Every registered bot has exactly one app. Aunque no es posible para el propietario de un bot cambiar de manera independiente la aplicación que está asociada con su bot, el equipo de Bot Framework sí que puede hacerlo en un pequeño número de casos excepcionales.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.

Los bots y los canales pueden usar los identificadores de aplicación para identificar de forma única a un bot registrado.Bots and channels may use app IDs to uniquely identify a registered bot.

Los identificadores de aplicación son siempre GUID.App IDs are guaranteed to be GUIDs. Los identificadores de aplicación se deben comparar sin diferenciar entre mayúsculas y minúsculas.App IDs should be compared without case sensitivity.

Reglas para los identificadores de aplicaciónRules for app IDs

  • Los identificadores de aplicación son únicos (comparación GUID) dentro de la plataforma de Microsoft App.App IDs are unique (GUID comparison) within the Microsoft App platform.
  • Cada bot tiene exactamente una aplicación correspondiente.Every bot has exactly one corresponding app.
  • El cambio de la aplicación que está asociada a un bot requiere la ayuda del equipo de Bot Framework.Changing which app a bot is associated with requires the assistance of the Bot Framework team.

Cuenta de canalChannel Account

Cada bot y usuario tienen una cuenta dentro de cada canal.Every bot and user has an account within each channel. La cuenta contiene un identificador (id) y otros datos informativos no estructurales del bot, como un nombre opcional.The account contains an identifier (id) and other informative bot non-structural data, like an optional name.

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

Esta cuenta describe la dirección dentro del canal donde se pueden enviar y recibir mensajes.This account describes the address within the channel where messages may be sent and received. En algunos casos, estos registros existen dentro de un único servicio (p. ej. Facebook).In some cases, these registrations exist within a single service (e.g., Facebook). En otros casos, se registran en varios sistemas (direcciones de correo electrónico, números de teléfono).In others, they are registered across many systems (email addresses, phone numbers). En los canales más anónimos (p. ej. Chat en web), el registro puede ser efímero.In more anonymous channels (e.g., Web Chat), the registration may be ephemeral.

Las cuentas de canal están anidadas dentro de los canales.Channel accounts are nested within channels. Una cuenta de Facebook, por ejemplo, es simplemente un número.A Facebook account, for example, is simply a number. Este número puede tener un significado diferente en otros canales, y no tiene significado fuera de todos los canales.This number may have a different meaning in other channels, and it doesn't have meaning outside all channels.

La relación entre las cuentas de canal y los usuarios (personas reales) depende de las convenciones asociadas a cada canal.The relationship between channel accounts and users (actual people) depends on conventions associated with each channel. Por ejemplo, un número SMS suele hacer referencia a una persona durante un período de tiempo, pasado este tiempo el número se puede transferir a otra persona.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. Por el contrario, una cuenta de Facebook suele hacer referencia a una persona de forma perpetua, aunque no es raro que dos personas compartan una cuenta de 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.

En la mayoría de los canales, se puede pensar en una cuenta de canal como una especie de buzón donde se pueden entregar mensajes.In most channels, it's appropriate to think of a channel account as a kind of mailbox where messages can be delivered. Es habitual que la mayoría de los canales permitan que varias direcciones se asignen a un solo buzón; Por ejemplo, "jdoe@contoso.com"y"john.doe@service.contoso.com" se pueden resolver con la misma bandeja de entrada.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. Algunos canales van más allá y modifican la dirección de la cuenta en función de qué bot tiene acceso a ella; por ejemplo, Facebook altera los identificadores de usuario para que cada bot tenga una dirección diferente para enviar y recibir mensajes.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.

Aunque en algunos casos se puede establecer la equivalencia entre las direcciones, el establecimiento de equivalencias entre los buzones y equivalencias entre personas requiere el conocimiento de las convenciones dentro del canal, y en muchos casos no es posible.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.

El bot recibe información de su dirección de cuenta de canal en el campo recipient en las actividades que se envían al bot.A bot is informed of its channel account address via the recipient field on activities sent to the bot.

Reglas para las cuentas de canalRules for channel accounts

  • Las cuentas de canal tienen significado solo dentro de su canal asociado.Channel accounts have meaning only within their associated channel.
  • Se puede resolver más de un identificador a la misma cuenta.More than one ID may resolve to the same account.
  • La comparación ordinal puede utilizarse para establecer que dos identificadores son el mismo.Ordinal comparison may be used to establish that two IDs are the same.
  • Normalmente, no hay ninguna comparación que puede usarse para identificar si dos identificadores diferentes se resuelven a la misma cuenta, bot o persona.There is generally no comparison that can be used to identify whether two different IDs resolve to the same account, bot or person.
  • La estabilidad de las asociaciones entre identificadores, cuentas, buzones y personas depende del canal.The stability of associations between IDs, accounts, mailboxes, and people depends on the channel.

Identificador de conversaciónConversation ID

Los mensajes se envían y reciben en el contexto de una conversación, que se puede reconocer por su identificador.Messages are sent and received in the context of a conversation, which is identifiable by ID.

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

Una conversación contiene un intercambio de mensajes y otras actividades.A conversation contains an exchange of messages and other activities. Cada conversación tiene cero o más actividades, y cada actividad aparece exactamente en una conversación.Every conversation has zero or more activities, and every activity appears in exactly one conversation. Las conversaciones pueden ser perpetuas, o pueden tener principios y finales claros.Conversations may be perpetual, or may have distinct starts and ends. El proceso de creación, modificación o finalización de una conversación se produce dentro del canal (es decir, una conversación existe cuando el canal es consciente de ello), y es el canal el que establece las características de estos procesos.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.

Las actividades dentro de una conversación las envían los usuarios y los bots.The activities within a conversation are sent by users and bots. La definición para la que los usuarios "participan" en una conversación varía según el canal, y puede incluir, en teoría, a los usuarios actuales, los usuarios que nunca han recibido un mensaje y los usuarios que hayan enviado un mensaje.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.

Varios canales (por ejemplo, SMS y posiblemente otros) tienen la peculiaridad de que el identificador de conversación asignado a una conversación de 1 a 1 es el identificador de cuenta del canal remoto.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. Esta peculiaridad tiene dos efectos secundarios:This quirk has two side-effects:

  1. El identificador de conversación es subjetivo en base a quién lo esté viendo.The conversation ID is subjective based on who is viewing it. Si los participantes A y B están hablando, el participante A ve el identificador de conversación como "B" mientras el participante B ve el identificador de conversación como "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 el bot tiene varias cuentas de canal dentro de este canal (por ejemplo, si el bot tiene dos números SMS), el identificador de conversación no es suficiente para identificar de forma exclusiva la conversación dentro campo de vista del 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.

Por lo tanto, un identificador de conversación no identifica necesariamente una sola conversación dentro de un canal, incluso para un solo bot.Thus, a conversation ID does not necessarily uniquely identify a single conversation within a channel even for a single bot.

Reglas para los identificadores de conversaciónRules for conversation IDs

  • Las conversaciones tienen significado solo dentro de su canal asociado.Conversations have meaning only within their associated channel.
  • Se puede resolver más de un identificador a la misma conversación.More than one ID may resolve to the same conversation.
  • La igualdad ordinal no establece necesariamente que dos identificadores de conversación son la misma conversación, aunque en la mayoría de los casos, sí lo hace.Ordinal equality does not necessarily establish that two conversation IDs are the same conversation, although in most cases, it does.

Identificador de actividadActivity ID

Las actividades se envían y reciben dentro del protocolo de Bot Framework y a veces son identificables.Activities are sent and received within the Bot Framework protocol, and these are sometimes identifiable.

Ejemplo: "id": "5678"Example: "id": "5678"

Los identificadores de actividad son opcionales y los emplean los canales para dar al bot una manera de hacer referencia al identificador en llamadas API posteriores, si están 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:

  • Respuesta a una actividad específicaReplying to a particular activity
  • Consulta de la lista de participantes en el nivel de actividadQuerying for the list of participants at the activity level

Dado que no se han establecido más casos de uso, no hay reglas adicionales para el tratamiento de los identificadores de actividad.Because no further use cases have been established, there are no additional rules for the treatment of activity IDs.