Campos de ID no Bot Framework

APLICA-SE A: SDK v4

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

ID do canal

Cada canal do Bot Framework é identificado por uma ID exclusiva.

Exemplo: "channelId": "slack"

As IDs de canal servem como namespaces para outras IDs. As chamadas de runtime no protocolo Bot Framework devem ocorrer no contexto de um canal; o canal dá significado às IDs de conversa e conta usadas durante a comunicação.

Por convenção, todas as IDs de canal são minúsculas. Os canais garantem que as IDs de canal que emitem têm maiúsculas e minúsculas consistentes e, portanto, os bots podem usar comparações ordinais para estabelecer a equivalência.

Regras para IDs de canal

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

Identificador de bot

Cada bot que foi registrado no Serviço de Bot de IA do Azure 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 é associado a um ponto de extremidade de webhook HTTP e 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 as variações de maiúsculas e minúsculas do identificador de bot são tratadas como um único identificador), embora essa seja uma característica do portal do Azure e não necessariamente o próprio identificador do bot.

Regras para identificadores de bot

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

ID do aplicativo

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

Nota

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

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

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

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

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

As IDs do aplicativo têm garantia de serem GUIDs. As IDs do aplicativo devem ser comparadas sem a confidencialidade de maiúsculas e minúsculas.

Regras para IDs de aplicativo

• As IDs do aplicativo são exclusivas (comparação guid) na plataforma microsoft app.
• Cada bot tem exatamente um aplicativo correspondente.
• Alterar o aplicativo ao qual um bot está associado requer a assistência da equipe do Bot Framework.

Conta de canal

Cada bot e usuário tem uma conta em 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" }

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

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

A relação entre contas de canal e usuários (pessoas reais) depende de convenções associadas a cada canal. Por exemplo, um número de SMS normalmente se refere 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 uma espécie de caixa de correio em que as mensagens podem ser entregues. É comum 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 resolver para a mesma caixa de entrada. Alguns canais vão além e alteram o endereço da conta com base em qual bot está acessando-o. Por exemplo, o Facebook altera as 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 de seu endereço de conta de canal por meio do campo recipient em atividades enviadas ao bot.

Regras para contas de canal

• As contas de canal têm significado somente no canal associado.
• Mais de uma ID pode ser resolvida para a mesma conta.
• A comparação ordinal pode ser usada para estabelecer que duas IDs são as mesmas.
• Geralmente, não há nenhuma comparação que possa ser usada para identificar se duas IDs diferentes são resolvidas 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

As mensagens são enviadas e recebidas no contexto de uma conversa, que é identificável pela 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 podem ter inícios e términos distintos. O processo de criação, modificação ou término de uma conversa ocorre dentro do canal — uma conversa só existe enquanto o canal está ciente dele — 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 a ID da conversa atribuída a uma conversa 1:1 é a ID da conta de canal remoto. Essa peculiaridade tem dois efeitos colaterais:

1. A ID da conversa é subjetiva, com base em quem a está exibindo. Se os participantes A e B estiverem conversando, o participante A verá a ID da conversa como "B" e o participante B verá a 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), a ID da conversa não será suficiente para identificar exclusivamente a conversa dentro do campo de exibição do bot.

Portanto, uma 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

• As conversas têm significado somente dentro do canal associado.
• Mais de uma ID pode ser resolvida para a mesma conversa.
• A igualdade ordinal não necessariamente estabelece que duas IDs de conversa são a mesma conversa, embora na maioria dos casos, sim.

ID da atividade

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

Exemplo: "id": "5678"

As IDs de atividade são opcionais e empregadas por canais para dar ao bot uma maneira de referenciar a ID em chamadas à API subsequentes, se estiverem disponíveis:

• Respondendo a uma atividade específica
• Consultando a lista de participantes no 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.