Campos ID no Bot Framework

SE APLICA A: SDK v4

Este guia descreve as características dos campos ID no Bot Framework.

ID do canal

Cada canal do Bot Framework é identificado por um ID exclusivo.

Exemplo: "channelId": "slack"

Os IDs de canal servem como namespaces para outros IDs. As chamadas de tempo de execução no protocolo Bot Framework devem ocorrer dentro do contexto de um canal; o canal dá significado à conversa e aos IDs de conta usados na comunicação.

Por convenção, todos os IDs de canal são minúsculos. Os canais garantem que os IDs de canal que emitem tenham invólucro consistente e, portanto, os bots podem usar comparações ordinais para estabelecer equivalência.

Regras para IDs de canal

• Os IDs de canal diferenciam maiúsculas de minúsculas.

Punho do Bot

Cada bot que foi registrado com o Serviço de Bot do Azure AI tem um identificador de bot.

Exemplo: FooBot

Um identificador de bot representa o registro de um bot com o Serviço de Bot de IA do Azure online. Esse registro está associado a um ponto de extremidade de webhook HTTP e a registros com canais.

O Serviço de Bot de IA do Azure garante a exclusividade dos identificadores de bot. O portal do Azure executa uma verificação de exclusividade que não diferencia maiúsculas de minúsculas (o que significa que variações de maiúsculas e minúsculas do identificador de bot são tratadas como um identificador único), embora essa seja uma característica do portal do Azure e não necessariamente do identificador de bot em si.

Regras para identificadores de bot

• Os identificadores de bot são exclusivos (não diferenciam maiúsculas de minúsculas) dentro do Bot Framework.

ID do aplicativo

Cada bot que foi registrado no Serviço de Bot do Azure AI tem uma ID de Aplicativo.

Observação

Anteriormente, os aplicativos eram comumente chamados de "Aplicativos MSA" ou "Aplicativos MSA/AAD". Os aplicativos agora são mais comumente referidos simplesmente como "aplicativos", mas alguns elementos de protocolo podem se referir aos aplicativos como "MSA Apps" perpetuamente.

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

Um aplicativo representa um registro no portal de aplicativos da equipe de identidade e serve como o mecanismo de identidade de serviço a serviço dentro do protocolo de tempo de execução do Bot Framework. Os aplicativos podem ter outras associações que não sejam de bots, como sites e aplicativos móveis/de desktop.

Cada bot registrado tem exatamente um aplicativo. Embora não seja possível para um proprietário de bot alterar independentemente qual aplicativo está associado ao seu bot, a equipe do Bot Framework pode fazer isso em alguns casos excecionais.

Bots e canais podem usar IDs de aplicativos para identificar exclusivamente um bot registrado.

Os IDs de aplicativo são garantidos como GUIDs. Os IDs do aplicativo devem ser comparados sem diferenciação de maiúsculas e minúsculas.

Regras para IDs de aplicativos

• As IDs de aplicativo são exclusivas (comparação GUID) dentro da plataforma Microsoft App.
• Cada bot tem exatamente um aplicativo correspondente.
• Alterar a qual aplicativo um bot está associado requer a assistência da equipe do Bot Framework.

Conta do canal

Cada bot e usuário tem uma conta dentro de cada canal. A conta contém um identificador (id) e outros dados não estruturais do bot informativo, como um nome opcional.

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

Esta conta descreve o endereço dentro do canal onde as mensagens podem ser enviadas e recebidas. Em alguns casos, esses registros existem dentro de um único serviço, como o Facebook. Em outros, eles são registrados em muitos sistemas (endereços de e-mail, números de telefone). Em canais mais anónimos, como o Web Chat, o registo pode ser efémero.

As contas de canal são aninhadas em canais. Uma conta no Facebook, por exemplo, é simplesmente um número. Este número pode ter um significado diferente em outros canais, e não tem significado fora de todos os canais.

A relação entre as contas do canal e os usuários (pessoas reais) depende das convenções associadas a cada canal. Por exemplo, um número de SMS normalmente refere-se a uma pessoa, mas o número pode ser transferido para outra pessoa. Por outro lado, uma conta do Facebook normalmente se refere a uma pessoa em perpetuidade, embora não seja incomum que duas pessoas compartilhem uma conta do Facebook.

Na maioria dos canais, é apropriado pensar em uma conta de canal como um tipo de caixa de correio onde as mensagens podem ser entregues. É típico que a maioria dos canais permita que vários endereços sejam mapeados para uma única caixa de correio. Por exemplo, "jdoe@contoso.com" e "john.doe@service.contoso.com" podem ser resolvidos para a mesma caixa de entrada. Alguns canais vão um passo além e alteram o endereço da conta com base em qual bot está acessando-a. Por exemplo, o Facebook altera IDs de usuário para que cada bot tenha um endereço diferente para enviar e receber mensagens.

Embora seja possível, em alguns casos, estabelecer equivalência entre endereços, estabelecer equivalência entre caixas de correio e equivalência entre pessoas requer conhecimento das convenções dentro do canal e, em muitos casos, não é possível.

Um bot é informado do endereço da conta do canal através do campo recipient nas atividades enviadas para o bot.

Regras para contas de canal

• As contas de canal têm significado apenas dentro do canal associado.
• Mais de um ID pode ser resolvido para a mesma conta.
• A comparação ordinal pode ser usada para estabelecer que dois IDs são iguais.
• Geralmente, não há comparação que possa ser usada para identificar se dois IDs diferentes são resolvidos para a mesma conta, bot ou pessoa.
• A estabilidade das associações entre IDs, contas, caixas de correio e pessoas depende do canal.

ID da conversação

As mensagens são enviadas e recebidas no contexto de uma conversa, que é identificável pelo ID.

Exemplo: "conversation": { "id": "1234" }

Uma conversa contém uma troca de mensagens e outras atividades. Cada conversa tem zero ou mais atividades, e cada atividade aparece exatamente em uma conversa. As conversas podem ser perpétuas ou ter inícios e fins distintos. O processo de criar, modificar ou encerrar uma conversa ocorre dentro do canal – uma conversa só existe enquanto o canal está ciente dela – e as características desses processos são estabelecidas pelo canal.

As atividades dentro de uma conversa são enviadas por usuários e bots. A definição para a qual os usuários "participam" de uma conversa varia de acordo com o canal, e teoricamente pode incluir usuários presentes, usuários que já receberam uma mensagem, usuários que enviaram uma mensagem.

Vários canais, como SMS e possivelmente outros, têm a peculiaridade de que o ID de conversa atribuído a uma conversa 1:1 é o ID da conta do canal remoto. Esta peculiaridade tem dois efeitos colaterais:

1. O ID da conversa é subjetivo, baseado em quem o está visualizando. Se os participantes A e B estiverem falando, o participante A verá o ID da conversa como "B" e o participante B verá o ID da conversa como "A".
2. Se o bot tiver várias contas de canal dentro desse canal (por exemplo, se o bot tiver dois números de SMS), o ID da conversa não será suficiente para identificar exclusivamente a conversa dentro do campo de visão do bot.

Assim, um ID de conversa não necessariamente identifica exclusivamente uma única conversa dentro de um canal, mesmo para um único bot.

Regras para IDs de conversação

• As conversas têm significado apenas dentro do canal associado.
• Mais de um ID pode resolver a mesma conversa.
• A igualdade ordinal não estabelece necessariamente que dois IDs de conversação são a mesma conversa, embora, na maioria dos casos, isso aconteça.

ID da atividade

As atividades são enviadas e recebidas dentro do protocolo Bot Framework e, às vezes, são identificáveis.

Exemplo: "id": "5678"

Os IDs de atividade são opcionais e empregados pelos canais para dar ao bot uma maneira de referenciar o ID em chamadas de API subsequentes, se estiverem disponíveis:

• Responder a uma atividade específica
• Consultar a lista de participantes ao nível da atividade

Como não foram estabelecidos mais casos de uso, não há regras adicionais para o tratamento de IDs de atividade.