Obtenha o contexto específico do Teams para seu bot
Artigo
7 minutos para o fim da leitura
Importante
Os exemplos de código nesta seção são baseados na versão 4.6 e versões posteriores do SDK da Estrutura de Bot. Se você estiver procurando documentação para versões anteriores, consulte a seção bots - V3 SDK na pasta Recursos da documentação.
Um bot pode acessar dados de contexto adicionais sobre uma equipe ou chat onde está instalado. Essas informações podem ser usadas para enriquecer a funcionalidade do bot e fornecer uma experiência mais personalizada.
Buscar a lista ou perfil de usuário
Seu bot pode consultar a lista de membros e seus perfis de usuário básicos, incluindo IDs de usuário do Teams e informações do Microsoft Azure Active Directory (Azure AD), como nome e objectId. Você pode usar essas informações para correlacionar identidades de usuários. Por exemplo, para verificar se um usuário conectado a uma guia por meio de credenciais do Azure Active Directory, é um membro da equipe. Para obter membros da conversa, o tamanho mínimo ou máximo da página depende da implementação. Tamanho de página menor que 50, são tratados como 50 e maiores que 500, são limitados a 500. Mesmo se você usar a versão não paginada, ela não é confiável em grandes equipes e não deve ser usada. Para obter mais informações, alterações nas APIs de Bot do Teams para buscar membros da equipe ou de chat.
O código de amostra a seguir usa o ponto de extremidade paginado para buscar a lista:
public class MyBot : TeamsActivityHandler
{
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
var members = new List<TeamsChannelAccount>();
string continuationToken = null;
do
{
var currentPage = await TeamsInfo.GetPagedMembersAsync(turnContext, 100, continuationToken, cancellationToken);
continuationToken = currentPage.ContinuationToken;
members.AddRange(currentPage.Members);
}
while (continuationToken != null);
}
}
export class MyBot extends TeamsActivityHandler {
constructor() {
super();
// See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
this.onMessage(async (turnContext, next) => {
var continuationToken;
var members = [];
do {
var pagedMembers = await TeamsInfo.getPagedMembers(turnContext, 100, continuationToken);
continuationToken = pagedMembers.continuationToken;
members.push(...pagedMembers.members);
}
while(continuationToken !== undefined)
// By calling next() you ensure that the next BotHandler is run.
await next();
});
}
}
Você pode emitir diretamente uma solicitação GET em /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}, usando o valor de serviceUrl como ponto de extremidade. O valor de serviceUrl é estável, mas pode ser alterado. Quando uma nova mensagem chega, o bot deve verificar seu valor armazenado para serviceUrl. A carga de resposta também indica se o usuário é um usuário normal ou anônimo.
Depois de buscar a lista ou perfil de usuário, você pode obter detalhes de um único membro. Atualmente, para recuperar informações de um ou mais membros de um chat ou equipe, use as APIs de bot do Microsoft Teams TeamsInfo.GetMembersAsync para C# ou TeamsInfo.getMembers para APIs TypeScript.
Obter detalhes de membro único
Você também pode recuperar os detalhes de um usuário específico usando sua ID de usuário, UPN ou ID de Objeto do Azure Active Directory do Teams.
O código de exemplo a seguir é usado para obter detalhes de um único membro:
public class MyBot : TeamsActivityHandler
{
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
var member = await TeamsInfo.GetMemberAsync(turnContext, turnContext.Activity.From.Id, cancellationToken);
}
}
export class MyBot extends TeamsActivityHandler {
constructor() {
super();
// See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
this.onMessage(async (turnContext, next) => {
const member = await TeamsInfo.getMember(turnContext, encodeURI('someone@somecompany.com'));
// By calling next() you ensure that the next BotHandler is run.
await next();
});
}
}
Você pode emitir diretamente uma solicitação GET em /v3/conversations/{conversationId}/members/{userId}, usando o valor de serviceUrl como ponto de extremidade. O valor de serviceUrl é estável, mas pode ser alterado. Quando uma nova mensagem chega, o bot deve verificar seu valor armazenado para serviceUrl. Isso pode ser usado para usuários regulares e usuários anônimos.
A seguir está a amostra de resposta para usuário comum:
GET /v3/conversations/19:ja0cu120i1jod12j@skype.net/members/29:1GcS4EyB_oSI8A88XmWBN7NJFyMqe3QGnJdgLfFGkJnVelzRGos0bPbpsfJjcbAD22bmKc4GMbrY2g4JDrrA8vM06X1-cHHle4zOE6U4ttcc
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",
"tenantId":"72f988bf-86f1-41af-91ab-2d7cd011db47",
"userRole":"user"
}
Veja a seguir a amostra de resposta para usuário anônimo:
GET /v3/conversations/19:ja0cu120i1jod12j@skype.net/members/<anonymous user id>"
Response body
{
"id": "29:1GcS4EyB_oSI8A88XmWBN7NJFyMqe3QGnJdgLfFGkJnVelzRGos0bPbpsfJjcbAD22bmKc4GMbrY2g4JDrrA8vM06X1-cHHle4zOE6U4ttcc",
"name": "Anon1 (Guest)",
"tenantId":"72f988bf-86f1-41af-91ab-2d7cd011db47",
"userRole":"anonymous"
}
Depois de obter detalhes de um único membro, você pode obter detalhes da equipe. Atualmente, para recuperar informações de uma equipe, use as APIs de bot do Teams TeamsInfo.GetMemberDetailsAsync para C# ou TeamsInfo.getTeamDetails para TypeScript.
Obter detalhes da equipe
Quando instalado em uma equipe, seu bot pode consultar metadados sobre essa equipe, incluindo a ID de grupo do Azure Active Directory.
O código de exemplo a seguir é usado para obter os detalhes da equipe:
public class MyBot : TeamsActivityHandler
{
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
TeamDetails teamDetails = await TeamsInfo.GetTeamDetailsAsync(turnContext, turnContext.Activity.TeamsGetTeamInfo().Id, cancellationToken);
if (teamDetails != null) {
await turnContext.SendActivityAsync($"The groupId is: {teamDetails.AadGroupId}");
}
else {
await turnContext.SendActivityAsync($"Message did not come from a channel in a team.");
}
}
}
export class MyBot extends TeamsActivityHandler {
constructor() {
super();
// See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
this.onMessage(async (turnContext, next) => {
const teamDetails = await TeamsInfo.getTeamDetails(turnContext);
if (teamDetails) {
await turnContext.sendActivity(`The group ID is: ${teamDetails.aadGroupId}`);
} else {
await turnContext.sendActivity('This message did not come from a channel in a team.');
}
// By calling next() you ensure that the next BotHandler is run.
await next();
});
}
}
async def _show_details(self, turn_context: TurnContext):
team_details = await TeamsInfo.get_team_details(turn_context)
reply = MessageFactory.text(f"The team name is {team_details.name}. The team ID is {team_details.id}. The AADGroupID is {team_details.aad_group_id}.")
await turn_context.send_activity(reply)
Você pode emitir diretamente uma solicitação GET em /v3/teams/{teamId}, usando o valor de serviceUrl como ponto de extremidade. O valor de serviceUrl é estável, mas pode ser alterado. Quando uma nova mensagem chega, o bot deve verificar seu valor armazenado para serviceUrl.
GET /v3/teams/19:ja0cu120i1jod12j@skype.net
Response body
{
"id": "29:1GcS4EyB_oSI8A88XmWBN7NJFyMqe3QGnJdgLfFGkJnVelzRGos0bPbpsfJjcbAD22bmKc4GMbrY2g4JDrrA8vM06X1-cHHle4zOE6U4ttcc",
"name": "The Team Name",
"aadGroupId": "02ce3874-dd86-41ba-bddc-013f34019978"
}
Depois de obter os detalhes da equipe, você pode obter a lista de canais em uma equipe. Atualmente, para recuperar informações de uma lista de canais em uma equipe, use as APIs de bot do Teams TeamsInfo.GetTeamChannelsAsync para C# ou TeamsInfo.getTeamChannels para APIs TypeScript.
Obter 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.
O código de exemplo a seguir é usado para obter a lista de canais em uma equipe:
public class MyBot : TeamsActivityHandler
{
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
IEnumerable<ChannelInfo> channels = await TeamsInfo.GetTeamChannelsAsync(turnContext, turnContext.Activity.TeamsGetTeamInfo().Id, cancellationToken);
await turnContext.SendActivityAsync($"The channel count is: {channels.Count()}");
}
}
export class MyBot extends TeamsActivityHandler {
constructor() {
super();
// See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
this.onMessage(async (turnContext, next) => {
const channels = await TeamsInfo.getTeamChannels(turnContext);
await turnContext.sendActivity(`The channel count is: ${channels.length}`);
// By calling next() you ensure that the next BotHandler is run.
await next();
});
}
}
async def _show_channels(
self, turn_context: TurnContext
):
channels = await TeamsInfo.get_team_channels(turn_context)
reply = MessageFactory.text(f"Total of {len(channels)} channels are currently in team")
await turn_context.send_activity(reply)
Você pode emitir diretamente uma solicitação GET em /v3/teams/{teamId}/conversations, usando o valor de serviceUrl como ponto de extremidade. O valor de serviceUrl é estável, mas pode ser alterado. Quando uma nova mensagem chega, o bot deve verificar seu valor armazenado para serviceUrl.