Obtención del contexto específico de Teams para un bot
Artículo
Importante
Los ejemplos de código de esta sección se basan en la versión 4.6 y versiones posteriores del SDK de Bot Framework. Si busca documentación para versiones anteriores, consulte la sección bots - v3 SDK en la carpeta SDK heredados de la documentación.
Un bot puede acceder a datos de contexto adicionales sobre un equipo o el chat donde está instalado. Esta información se puede usar para enriquecer la funcionalidad del bot y proporcionar una experiencia más personalizada.
Captura de la lista o el perfil del usuario
El bot puede consultar la lista de miembros y sus perfiles de usuario básicos, incluidos los identificadores de usuario de Teams y la información de Microsoft Entra, como name y objectId. Puede usar esta información para correlacionar las identidades de usuario. Por ejemplo, para comprobar si un usuario ha iniciado sesión en una pestaña a través de las credenciales de Microsoft Entra es miembro del equipo. Para obtener miembros de la conversación, el tamaño mínimo o máximo de la página depende de la implementación. El tamaño de página menor que 50, se trata como 50 y mayor que 500, se limita a 500. Incluso si usa la versión no paginada, no es confiable en equipos grandes y no se debe usar. Para obtener más información, consulte cambios en las API del bot de Teams para capturar miembros del equipo o del chat.
Nota:
La paginación está disponible en un equipo y un canal.
La paginación no se admite en los chats. En el caso de los chats, siempre se devuelve toda la lista.
El código de ejemplo siguiente usa el punto de conexión paginado para capturar la 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)
Puede emitir directamente una solicitud GET en /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}, utilizando el valor de serviceUrl como punto de conexión. El valor de serviceUrl es estable, pero puede cambiar. Cuando llega un nuevo mensaje, el bot debe comprobar su valor almacenado para serviceUrl. La carga de respuesta también indica si el usuario es un usuario normal o anónimo.
Después de capturar la lista o el perfil de usuario, puede obtener detalles de un único miembro. Para recuperar información de uno o varios miembros de un chat o equipo, use las API TeamsInfo.GetMembersAsync de bot de Microsoft Teams para C# o TeamsInfo.getMembers para las API de TypeScript.
Obtener detalles de un miembro
También puede recuperar los detalles de un usuario determinado mediante su id. de usuario, UPN o id. de objeto de Microsoft Entra de Teams.
El siguiente código de ejemplo se usa para obtener detalles de un solo miembro:
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)
Puede emitir directamente una solicitud GET en /v3/conversations/{conversationId}/members/{userId}, utilizando el valor de serviceUrl como punto de conexión. El valor de serviceUrl es estable, pero puede cambiar. Cuando llega un nuevo mensaje, el bot debe comprobar su valor almacenado para serviceUrl. Esto se puede usar para usuarios normales y usuarios anónimos.
A continuación se muestra el ejemplo de respuesta para el usuario normal:
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"
}
A continuación se muestra el ejemplo de respuesta para el usuario 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"
}
Después de obtener los detalles de un solo miembro, puede obtener los detalles del equipo. Para recuperar información de un equipo, use las API TeamsInfo.GetMemberDetailsAsync de bot de Teams para C# o TeamsInfo.getTeamDetails para TypeScript.
Obtener los detalles del equipo
Cuando se instala en un equipo, el bot puede consultar metadatos sobre ese equipo, incluido el identificador de grupo de Microsoft Entra.
El siguiente código de ejemplo se usa para obtener los detalles del equipo:
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)
Puede emitir directamente una solicitud GET en /v3/teams/{teamId}, utilizando el valor de serviceUrl como punto de conexión. El valor de serviceUrl es estable, pero puede cambiar. Cuando llega un nuevo mensaje, el bot debe comprobar su valor almacenado 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"
}
Después de obtener los detalles del equipo, puede obtener la lista de canales de un equipo. Para recuperar información de una lista de canales de un equipo, use las API TeamsInfo.GetTeamChannelsAsync de bot de Teams para C# o TeamsInfo.getTeamChannels para las API de TypeScript.
Obtiene la lista de canales en un equipo
El bot puede consultar la lista de canales de un equipo.
Nota:
El nombre del canal predeterminado General se devuelve como null para permitir la localización.
El identificador de canal General siempre coincide con el identificador de equipo.
El siguiente código de ejemplo se usa para obtener la lista de canales de un equipo:
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)
Puede emitir directamente una solicitud GET en /v3/teams/{teamId}/conversations, utilizando el valor de serviceUrl como punto de conexión. El valor de serviceUrl es estable, pero puede cambiar. Cuando llega un nuevo mensaje, el bot debe comprobar su valor almacenado para serviceUrl.
El origen de este contenido se puede encontrar en GitHub, donde también puede crear y revisar problemas y solicitudes de incorporación de cambios. Para más información, consulte nuestra guía para colaboradores.