Obter contexto para o bot do Microsoft Teams

  • Artigo

Importante

Este artigo é baseado no SDK do Bot Framework v3. Se você estiver procurando a documentação atual versão 4.6 ou posterior do SDK, consulte a seção bots de conversação .

Seu bot pode acessar contexto adicional sobre a equipe ou chat, como perfil de usuário. Essas informações podem ser usadas para enriquecer a funcionalidade do bot e fornecer uma experiência mais personalizada.

Observação

  • As APIs de bot específicas do Microsoft Teams são melhor acessadas por meio de nossas extensões para o SDK do Construtor de Bots.
  • Para C# ou .NET, baixe nosso pacote NuGet Microsoft.Bot.Connector.Teams .
  • Para Node.js desenvolvimento, a funcionalidade Do Construtor de Bots para Teams é incorporada ao SDK do Bot Framework v4.6.

Buscar a lista de equipes

O bot pode consultar a lista de membros da equipe e seus perfis básicos. Os perfis básicos incluem IDs de usuário do Teams e informações de Microsoft Entra, como ID de nome e objeto. Você pode usar essas informações para correlacionar identidades de usuários. Por exemplo, marcar se um usuário conectado a uma guia por meio de credenciais Microsoft Entra for um membro da equipe.

Exemplo de API REST

Emita diretamente uma solicitação GET em /conversations/{teamId}/members/, usando o serviceUrl valor como ponto de extremidade.

O teamId pode ser encontrado no channeldata objeto da carga de atividade que seu bot recebe nos seguintes cenários:

Observação

  • Sempre use a ID da equipe ao chamar a API.
  • O serviceUrl valor tende a ser estável, mas pode ser alterado. Quando uma nova mensagem chega, o bot deve verificar seu valor armazenado serviceUrl .
GET /v3/conversations/19:ja0cu120i1jod12j@skype.net/members

Response body
[{
    "id": "29:1GcS4EyB_oSI8A88XmWBN7NJFyMqe3QGnJdgLfFGkJnVelzRGos0bPbpsfJjcbAD22bmKc4GMbrY2g4JDrrA8vM06X1-cHHle4zOE6U4ttcc",
    "objectId": "9d3e08f9-a7ae-43aa-a4d3-de3f319a8a9c",
    "givenName": "Larry",
    "surname": "Brown",
    "email": "Larry.Brown@fabrikam.com",
    "userPrincipalName": "labrown@fabrikam.com"
}, {
    "id": "29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk",
    "objectId": "76b0b09f-d410-48fd-993e-84da521a597b",
    "givenName": "John",
    "surname": "Patterson",
    "email": "johnp@fabrikam.com",
    "userPrincipalName": "johnp@fabrikam.com"
}, {
    "id": "29:1URzNQM1x1PNMr1D7L5_lFe6qF6gEfAbkdG8_BUxOW2mTKryQqEZtBTqDt10-MghkzjYDuUj4KG6nvg5lFAyjOLiGJ4jzhb99WrnI7XKriCs",
    "objectId": "6b7b3b2a-2c4b-4175-8582-41c9e685c1b5",
    "givenName": "Rick",
    "surname": "Stevens",
    "email": "Rick.Stevens@fabrikam.com",
    "userPrincipalName": "rstevens@fabrikam.com"
}]

Exemplo do .NET

Chame GetConversationMembersAsync usando Team.Id para retornar uma lista de IDs de usuário. Chame GetConversationMembersAsync para obter userRole a propriedade retornar o valor como usuário.

// Fetch the members in the current conversation
var connector = new ConnectorClient(new Uri(context.Activity.ServiceUrl));
var teamId = context.Activity.GetChannelData<TeamsChannelData>().Team.Id;
var members = await connector.Conversations.GetConversationMembersAsync(teamId);

// Concatenate information about all members into a string
var sb = new StringBuilder();
foreach (var member in members.AsTeamsChannelAccounts())
{
    sb.AppendFormat(
        "GivenName = {0}, TeamsMemberId = {1}",
        member.Name, member.Id);

    sb.AppendLine();
}

// Post the member info back into the conversation
await context.PostAsync($"People in this conversation: {sb.ToString()}");

Node.js ou exemplo typeScript


[...]
import * as builder from "botbuilder";
[...]

var teamId = session.message.sourceEvent.team.id;
connector.fetchMembers(
  (<builder.IChatConnectorAddress>session.message.address).serviceUrl,
  teamId,
  (err, result) => {
    if (err) {
      session.endDialog('There is some error');
    }
    else {
      session.endDialog('%s', JSON.stringify(result));
    }
  }
);

Buscar perfil de usuário ou lista no chat pessoal ou em grupo

Você pode fazer a chamada de API para qualquer chat pessoal para obter as informações de perfil do usuário conversando com seu bot.

A chamada de API, os métodos SDK e o objeto de resposta são idênticos à busca da lista de equipe. A única diferença é que você passa o conversationId em vez do teamId.

Buscar a lista de canais em uma equipe

Seu bot pode consultar a lista de canais em uma equipe.

Observação

  • O nome do canal geral padrão é retornado como null para permitir a localização.
  • A ID do canal para o canal Geral sempre corresponde à ID da equipe.

Exemplo de API REST

Emita diretamente uma solicitação GET em /teams/{teamId}/conversations/, usando o serviceUrl valor como ponto de extremidade.

A única fonte para teamId é uma mensagem do contexto da equipe. A mensagem é uma mensagem de um usuário ou a mensagem que seu bot recebe quando é adicionada a uma equipe. Para obter mais informações, consulte bot ou usuário adicionado a uma equipe.

Observação

O serviceUrl valor tende a ser estável, mas pode ser alterado. Quando uma nova mensagem chega, o bot deve verificar seu valor armazenado serviceUrl .

GET /v3/teams/19%3A033451497ea84fcc83d17ed7fb08a1b6%40thread.skype/conversations

Response body
{
    "conversations": [{
        "id": "19:033451497ea84fcc83d17ed7fb08a1b6@thread.skype",
        "name": null
    }, {
        "id": "19:cc25e4aae50746ecbb11473bba24c70a@thread.skype",
        "name": "Materials"
    }, {
        "id": "19:b7b84cba410c406ba671dbbf5e0a3519@thread.skype",
        "name": "Design"
    }, {
        "id": "19:fc5db2aed489454e8f8c06829ed6c986@thread.skype",
        "name": "Marketing"
    }]
}

Exemplo do .NET

O exemplo a seguir usa a FetchChannelList chamada das extensões do Teams para o SDK do Construtor de Bots para .NET:

ConversationList channels = client.GetTeamsConnectorClient().Teams.FetchChannelList(activity.GetChannelData<TeamsChannelData>().Team.Id);

Exemplo de Node.js

O exemplo a seguir usa fetchChannelList a chamada das extensões do Teams para o SDK do Construtor de Bots para Node.js:

var teamId = session.message.sourceEvent.team.id;
connector.fetchChannelList(
  (session.message.address).serviceUrl,
  teamId,
  (err, result) => {
    if (err) {
      session.endDialog('There is an error');
    }
    else {
      session.endDialog('%s', JSON.stringify(result));
    }
  }
);

Obter clientInfo no contexto do bot

Você pode buscar o clientInfo dentro da atividade do bot. O clientInfo contém as seguintes propriedades:

  • Locale
  • País/Região
  • Plataforma
  • Timezone

Exemplo JSON

[
    {
        "type": "clientInfo",
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "Asia/Calcutta"
    }
]

Exemplo de C#

var connector = new ConnectorClient(new Uri(context.Activity.ServiceUrl));

{
    var clientinfo = context.Activity.Entities[0];
    await context.PostAsync($"ClientInfo: clientinfo ");
}

Confira também

Amostras do Bot Framework.