Obter contexto para o bot do Microsoft TeamsGet context for your Microsoft Teams bot

Importante

Os artigos desta seção são baseados no SDK do v3 bot Framework.The articles in this section are based on the v3 Bot Framework SDK. Se você estiver procurando a documentação atual (versão 4,6 ou posterior do SDK), consulte a seção bots de conversa .If you're looking for current documentation (version 4.6 or later of the SDK) see the Conversational Bots section.

Seu bot pode acessar contexto adicional sobre a equipe ou chat, como perfil de usuário.Your bot can access additional context about the team or chat, such as user profile. Essas informações podem ser usadas para enriquecer a funcionalidade do seu bot e fornecer uma experiência mais personalizada.This information can be used to enrich your bot's functionality and provide a more personalized experience.

Observação

Essas – APIs de bot específicas do Microsoft Teams são mais bem acessadas por meio de nossas extensões para o SDK do bot Builder.These Microsoft Teams–specific bot APIs are best accessed through our extensions for the Bot Builder SDK. Para o C#/.NET, baixe o pacote NuGet Microsoft. bot. Connector. Teams .For C#/.NET, download our Microsoft.Bot.Connector.Teams NuGet package. Para o desenvolvimento de Node.js, a funcionalidade do BotBuilder para Microsoft Teams foi incorporada ao SDK da estrutura de bot a partir da v 4.6.For Node.js development, the BotBuilder for Microsoft Teams functionality has been incorporated into the Bot Framework SDK as of v4.6.

Buscando a lista de equipesFetching the team roster

O bot pode consultar a lista de membros da equipe e seus perfis básicos, que inclui as IDs de usuário do Teams e as informações do Azure Active Directory (Azure AD), como nome e objectId.Your bot can query for the list of team members and their basic profiles, which includes Teams user IDs and Azure Active Directory (Azure AD) information such as name and objectId. Você pode usar essas informações para correlacionar as identidades do usuário; por exemplo, para verificar se um usuário conectado a uma guia por meio de credenciais do Azure AD é um membro da equipe.You can use this information to correlate user identities; for example, to check whether a user logged into a tab through Azure AD credentials is a member of the team.

Exemplo de API RESTREST API example

Você pode emitir diretamente uma solicitação GET no /conversations/{teamId}/members/ , usando o valor de serviceUrl como ponto de extremidade.You can directly issue a GET request on /conversations/{teamId}/members/, using the value of serviceUrl as the endpoint.

O teamId pode ser encontrado no channeldata objeto da carga de atividade que seu bot recebe nos seguintes cenários:The teamId can be found in the channeldata object of the activity payload that your bot receives in the following scenarios:

Observação

  • Certifique-se de usar a ID da equipe ao chamar a APIMake sure to use the team id when calling the api
  • O valor de serviceUrl tende a ser estável, mas pode ser alterado.The value of serviceUrl tends to be stable but can change. Quando uma nova mensagem chega, seu bot deve verificar seu valor armazenado de serviceUrl .When a new message arrives, your bot should verify its stored value of 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 .NET.NET example

Chamar GetConversationMembersAsync usando Team.Id para retornar uma lista de IDs de usuário.Call GetConversationMembersAsync using Team.Id to return a list of user IDs.

// 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()}");

Exemplo de Node.js/TypeScriptNode.js/TypeScript example


[...]
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));
    }
  }
);

Confira também exemplos da estrutura de bot.See also Bot Framework samples.

Buscando perfil de usuário ou lista no chat de grupo ou pessoalFetching user profile or roster in personal or group chat

Você também pode fazer a mesma chamada de API para qualquer chat pessoal para obter as informações de perfil do usuário batendo papo com seu bot.You can also make the same API call for any personal chat to obtain the profile information of the user chatting with your bot.

Os métodos de chamada de API e SDK são idênticos para buscar a lista de equipes, como é o objeto de resposta.The API call and SDK methods are identical to fetching the team roster, as is the response object. A única diferença é passar no conversationId lugar do teamId .The only difference is you pass the conversationId instead of the teamId.

Buscando a lista de canais em uma equipeFetching the list of channels in a team

O bot pode consultar a lista de canais de uma equipe.Your bot can query the list of channels in a team.

Observação

  • O nome do canal geral padrão é retornado como null permitir para localização.The name of the default General channel is returned as null to allow for localization.
  • A ID do canal geral sempre corresponde à ID da equipe.The channel ID for the General channel always matches the team ID.

Exemplo de API RESTREST API example

Você pode emitir diretamente uma solicitação GET no /teams/{teamId}/conversations/ , usando o valor de serviceUrl como ponto de extremidade.You can directly issue a GET request on /teams/{teamId}/conversations/, using the value of serviceUrl as the endpoint.

A única fonte de teamId é uma mensagem do contexto da equipe-uma mensagem de um usuário ou a mensagem que seu bot recebe quando é adicionada a uma equipe (consulte bot ou User Added to a Team).The only source for teamId is a message from the team context - either a message from a user or the message that your bot receives when it is added to a team (see Bot or user added to a team).

Observação

O valor de serviceUrl tende a ser estável, mas pode ser alterado.The value of serviceUrl tends to be stable but can change. Quando uma nova mensagem chega, seu bot deve verificar seu valor armazenado de serviceUrl .When a new message arrives, your bot should verify its stored value of 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 .NET.NET example

O exemplo a seguir usa a FetchChannelList chamada das extensões do Microsoft Teams para o SDK do bot Builder para .net:The following example uses the FetchChannelList call from the Microsoft Teams extensions for the Bot Builder SDK for .NET:

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

Exemplo de Node.jsNode.js example

O exemplo a seguir usa fetchChannelList a chamada das extensões do Microsoft Teams para o SDK do bot Builder para Node.js.The following example uses fetchChannelList call from the Microsoft Teams extensions for the Bot Builder SDK for 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));
    }
  }
);