Obtenha o contexto específico do Teams para seu bot
Artigo
Importante
Os exemplos de código nesta seção são baseados na versão 4.6 e versões posteriores do SDK do Bot Framework. Se você estiver procurando documentação para versões anteriores, consulte a seção bots – v3 SDK na pasta SDKs Herdados 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
O bot pode consultar a lista de membros e seus perfis de usuário básicos, incluindo IDs de usuário do Teams e Microsoft Entra informações, como nome e objectId. Você pode usar essas informações para correlacionar identidades de usuários. Por exemplo, para marcar se um usuário conectado a uma guia por meio de credenciais Microsoft Entra é 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.
Observação
A paginação está disponível em uma equipe e em um canal.
Não há suporte para paginação em chats. Para chats, toda a lista sempre é retornada.
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
{
// Gets a paginated list of members of one-on-one, group, or team conversation.
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://learn.microsoft.com/en-us/azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0 to learn more about the message and other activity types.
this.onMessage(async (turnContext, next) => {
var continuationToken;
var members = [];
do {
// Gets a paginated list of members of one-on-one, group, or team conversation.
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();
});
}
}
async def _show_members(
self, turn_context: TurnContext
):
# Get a conversationMember from a team.
members = await TeamsInfo.get_team_members(turn_context)
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 determinado usuário usando sua ID de usuário do Teams, UPN ou Microsoft Entra ID do objeto.
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)
{
// Gets the account of a single conversation member.
// This works in one-on-one, group, and team scoped conversations.
var member = await TeamsInfo.GetMemberAsync(turnContext, turnContext.Activity.From.Id, cancellationToken);
}
}
export class MyBot extends TeamsActivityHandler {
constructor() {
super();
// See learn.microsoft.com/en-us/azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0 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();
});
}
}
async def _show_members(
self, turn_context: TurnContext
):
# TeamsInfo.get_member: Gets the member of a team scoped conversation.
member = await TeamsInfo.get_member(turn_context, turn_context.activity.from_property.id)
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, o bot pode consultar metadados sobre essa equipe, incluindo a ID do grupo Microsoft Entra.
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)
{
// Gets the details for the given team id. This only works in team scoped conversations.
// TeamsGetTeamInfo: Gets the TeamsInfo object from the current activity.
TeamDetails teamDetails = await TeamsInfo.GetTeamDetailsAsync(turnContext, turnContext.Activity.TeamsGetTeamInfo().Id, cancellationToken);
if (teamDetails != null) {
await turnContext.SendActivityAsync($"The groupId is: {teamDetails.AadGroupId}");
}
else {
// Sends a message activity to the sender of the incoming activity.
await turnContext.SendActivityAsync($"Message did not come from a channel in a team.");
}
}
}
export class MyBot extends TeamsActivityHandler {
constructor() {
super();
// See https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0 to learn more about the message and other activity types.
this.onMessage(async (turnContext, next) => {
// Gets the details for the given team id.
const teamDetails = await TeamsInfo.getTeamDetails(turnContext);
if (teamDetails) {
// Sends a message activity to the sender of the incoming activity.
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):
# Gets the details for the given team id.
team_details = await TeamsInfo.get_team_details(turn_context)
# MessageFactory.text(): Specifies the type of text data in a message attachment.
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}.")
# Sends a message activity to the sender of the incoming activity.
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
{
// Override this in a derived class to provide logic specific to Message activities.
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
// Returns a list of channels in a Team. This only works in team scoped conversations.
IEnumerable<ChannelInfo> channels = await TeamsInfo.GetTeamChannelsAsync(turnContext, turnContext.Activity.TeamsGetTeamInfo().Id, cancellationToken);
// Sends a message activity to the sender of the incoming activity.
await turnContext.SendActivityAsync($"The channel count is: {channels.Count()}");
}
}
export class MyBot extends TeamsActivityHandler {
constructor() {
super();
// See https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0 to learn more about the message and other activity types.
this.onMessage(async (turnContext, next) => {
// Supports retrieving channels hosted by a team.
const channels = await TeamsInfo.getTeamChannels(turnContext);
// Sends a message activity to the sender of the incoming activity.
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
):
# Supports retrieving channels hosted by a team.
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.
A fonte deste conteúdo pode ser encontrada no GitHub, onde você também pode criar e revisar problemas e solicitações de pull. Para obter mais informações, confira o nosso guia para colaboradores.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.