Sobre os consumidores de habilidades

APLICA-SE A: SDK v4

Um consumidor de skill é um bot que pode invocar um ou mais skills. Em relação aos skills, um bot raiz é um bot voltado para o usuário que também é um consumidor de skills.

Da perspectiva do usuário, o bot raiz é o bot com o qual ele está interagindo. Da perspectiva do skill, o consumidor de skills é o canal pelo qual ele se comunica com o usuário. (Para obter mais informações, confira a Visão geral das habilidades.)

Como um consumidor de skills, um bot raiz inclui algumas lógicas adicionais para gerenciar o tráfego entre ele e um skill:

• Informações de configuração para cada skill que a raiz usa.
• Um alocador de ID de conversa que permite que a raiz alterne entre a conversa que está tendo com o usuário e a que está tendo com uma habilidade.
• Um cliente de skills que pode empacotar e encaminhar atividades para um bot de skills.
• Um manipulador de skills que pode receber solicitações e desempacotar atividades de um bot skill.

Gerenciando skills

O início e a permissão de execução de uma só habilidade até a conclusão são gerenciados com algumas adições ao consumidor de habilidades. Cenários mais complicados são possíveis, com várias habilidades ou threads de conversa.

Um consumidor de habilidade implementa pelo menos dois pontos de extremidade HTTP:

• Um ponto de extremidade de mensagens que recebe atividades do usuário ou canal. Esse é o ponto de extremidade de mensagens usual que todos os bots implementam.
• Um ponto de extremidade de host de habilidade que recebe atividades de uma habilidade. Atua como uma URL de retorno de chamada, a URL de serviço à qual a habilidade responde. (O consumidor de habilidade precisa emparelhar o código que recebe a solicitação do método HTTP de uma habilidade com um manipulador de habilidades.)

Descrições de skills

Para cada skill, adicione um objeto de skill do Bot Framework ao arquivo de configuração do consumidor de skills. Cada um terá uma ID, uma ID do aplicativo e um ponto de extremidade para a habilidade.

Propriedade	Descrição
ID	A ID ou a chave do skill, específica ao consumidor de skills.
ID do Aplicativo	O appId atribuído ao recurso bot quando o skill foi registrado no Azure.
Ponto de extremidade de skill	O ponto de extremidade de mensagens para o skill. Essa é a URL que o consumidor usará para se comunicar com o skill.

Cliente de skills e manipulador de skills

O consumidor de skills usa um cliente de skills para enviar atividades a um skill. O cliente:

• Seleciona uma atividade a ser enviada para a habilidade, seja de um usuário ou gerada pelo consumidor.
• Define a URL do serviço na atividade enviada para a habilidade para o ponto de extremidade do host de habilidade do consumidor.
• Substitui a referência de conversa original por uma para a conversa consumidora de skills.
• Adiciona um token de autenticação de bot para bot.
• Envia a atividade atualizada para o skill.

O consumidor de skills usa um manipulador de skills para receber atividades de um skill. O manipulador:

• Processa os métodos da API REST de Serviço de canal.
• Impõe a validação de autenticação e declarações.
• Recupera a referência de conversa original.
• Gera uma atividade para o adaptador do consumidor. Essa atividade sinalizará que o skill foi concluído ou que será uma atividade a ser encaminhada ao usuário.

Gerenciar uma habilidade diretamente

Você precisa adicionar lógica ao consumidor de skills para acompanhar os skills ativos. Cabe ao consumidor saber como gerenciar as habilidades em geral, se várias habilidades ativas podem ser mantidas paralelamente ou não, e assim por diante. Cenários específicos a serem considerados incluem:

• Inicio de uma nova conversa consumidora de skills. (Isso será associado a uma conversa específica entre consumidor e usuário.)
  • Para passar parâmetros para um skill, defina a propriedade valor na atividade inicial para o skill.
• Continuação de uma conversa consumidora de skills existente.
• Reconhecimento de uma atividade endOfConversation do skill como sinalizadora do fim de uma conversa consumidora de skills.
  • Para recuperar qualquer valor retornado de um skill, verifique a propriedade valor da atividade.
  • Para verificar por que o skill está terminando, verifique o parâmetro código da atividade, que pode indicar que o skill encontrou um erro.
• Cancelamento de um skill do consumidor enviando uma atividade endOfConversation para o skill.

Confira como Implementar um consumidor de habilidades para obter um consumidor que gerencia uma habilidade diretamente.

Gerenciar uma habilidade usando um diálogo de habilidade

Se estiver usando a biblioteca de diálogos, você poderá usar um diálogo de habilidade para gerenciar uma habilidade. Embora a caixa de diálogo de habilidade seja a caixa de diálogo ativa, ela encaminhará atividades para a habilidade associada.

• Ao criar a caixa de diálogo de habilidade, use o parâmetro opções de caixa de diálogo para fornecer todas as informações de que a caixa de diálogo precisa para gerenciar a habilidade, como a ID do aplicativo e a URL de retorno de chamada do consumidor, a fábrica da ID de conversa a ser usada, as propriedades da habilidade e assim por diante.
  • Se desejar gerenciar mais de uma habilidade como um diálogo, será necessário criar um diálogo de habilidade separado para cada habilidade.
  • De maneira geral, você adicionará o diálogo de habilidade a um diálogo de componente.
• Para iniciar a caixa de diálogo de habilidade, use o método begin do contexto da caixa de diálogo e forneça a ID da caixa de diálogo de habilidade. Use o parâmetro opções para fornecer a atividade que o consumidor enviará como a primeira atividade para a habilidade.
• Você pode cancelar ou interromper a caixa de diálogo de habilidade como faria com qualquer outra caixa de diálogo. Confira como manipular interrupções do usuário para ver um exemplo.

Confira como Usar um diálogo para consumir uma habilidade para obter um consumidor que usa um diálogo para gerenciar uma habilidade.

Como usar um modo de entrega de respostas esperadas

Bots e habilidades usam REST e JSON padrão do setor em HTTPS para comunicação. O fluxo normal de processamento de atividade começa quando o bot raiz recebe uma postagem de um canal no ponto de extremidade de mensagens. O bot raiz então envia a atividade para a habilidade para processamento. As respostas da habilidade são postadas de volta no ponto de extremidade do host de habilidade do bot raiz, e não no ponto de extremidade de mensagens. Por fim, as respostas são processadas posteriormente ou postadas de volta no canal pelo bot raiz. Esse fluxo normal pode ser alterado ao mudar o modo de entrega da atividade enviada para a habilidade. Se o modo de entrega estiver definido como "ExpectReplies", a habilidade não será postada de volta no ponto de extremidade do host de habilidade. Em vez disso, todas as atividades de resposta serão serializadas no corpo da resposta. O bot raiz então iterará essas atividades, processando-as de forma semelhante a como elas teriam sido processadas pelo ponto de extremidade do host de habilidade.

Para obter informações, confira o Modo de entrega na especificação da Atividade.