Obtenir le contexte spécifique à Teams pour votre bot
Article
Importante
Les exemples de code de cette section sont basés sur la version 4.6 et les versions ultérieures du Kit de développement logiciel (SDK) Bot Framework. Si vous recherchez de la documentation pour les versions antérieures, consultez la section bots - Kit de développement logiciel (SDK) v3 dans le dossier Kits de développement logiciel (SDK) hérités de la documentation.
Un bot peut accéder à des données contextuelles supplémentaires sur une équipe ou une conversation où il est installé. Ces informations peuvent être utilisées pour enrichir les fonctionnalités du bot et fournir une expérience plus personnalisée.
Récupérer la liste ou le profil utilisateur
Votre bot peut interroger la liste des membres et leurs profils utilisateur de base, y compris les ID d’utilisateur Teams et les informations de Microsoft Entra, telles que name et objectId. Vous pouvez utiliser ces informations pour mettre en corrélation les identités des utilisateurs. Par exemple, pour case activée si un utilisateur s’est connecté à un onglet via Microsoft Entra informations d’identification est membre de l’équipe. Pour obtenir les membres de la conversation, la taille de page minimale ou maximale dépend de l’implémentation. La taille de page inférieure à 50, est traitée comme 50 et supérieure à 500, est limitée à 500. Même si vous utilisez la version non paginée, elle n'est pas fiable dans les grandes équipes et ne doit pas être utilisée. Pour plus d'informations, voir les modifications apportées aux API du robot Teams pour la récupération des membres de l'équipe ou du chat.
Remarque
La pagination est disponible dans une équipe et un canal.
La pagination n’est pas prise en charge dans les conversations. Pour les conversations, la liste entière est toujours retournée.
L’exemple de code suivant utilise le point de terminaison paginé pour récupérer la liste :
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://zcusa.951200.xyz/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)
Vous pouvez émettre directement une requête GET sur /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}, en utilisant la valeur de serviceUrl comme point de terminaison. La valeur de serviceUrl est stable, mais peut changer. Lorsqu'un nouveau message arrive, votre robot doit vérifier sa valeur stockée pour serviceUrl. La charge utile de réponse indique également si l’utilisateur est un utilisateur normal ou anonyme.
Après avoir extrait la liste ou le profil utilisateur, vous pouvez obtenir les détails d’un seul membre. Pour récupérer des informations pour un ou plusieurs membres d’une conversation ou d’une équipe, utilisez les TeamsInfo.GetMembersAsync API de bot Microsoft Teams pour C# ou TeamsInfo.getMembers pour les API TypeScript.
Obtenir les détails d’un seul membre
Vous pouvez également récupérer les détails d’un utilisateur particulier à l’aide de son ID d’utilisateur Teams, de son UPN ou de son ID d’objet Microsoft Entra.
L’exemple de code suivant est utilisé pour obtenir les détails d’un membre unique :
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 zcusa.951200.xyz/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)
Vous pouvez émettre directement une requête GET sur /v3/conversations/{conversationId}/members/{userId}, en utilisant la valeur de serviceUrl comme point de terminaison. La valeur de serviceUrl est stable, mais peut changer. Lorsqu'un nouveau message arrive, votre robot doit vérifier sa valeur stockée pour serviceUrl. Il peut être utilisé pour les utilisateurs standard et les utilisateurs anonymes.
Voici l’exemple de réponse pour l’utilisateur 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"
}
Voici l’exemple de réponse pour l’utilisateur anonyme :
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"
}
Une fois que vous avez obtenu les détails d’un seul membre, vous pouvez obtenir les détails de l’équipe. Pour récupérer des informations pour une équipe, utilisez les API TeamsInfo.GetMemberDetailsAsync de bot Teams pour C# ou TeamsInfo.getTeamDetails pour TypeScript.
Obtenir les détails de l’équipe
Lorsqu’il est installé dans une équipe, votre bot peut interroger les métadonnées relatives à cette équipe, y compris l’ID de groupe Microsoft Entra.
L’exemple de code suivant est utilisé pour obtenir les détails de l’équipe :
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://zcusa.951200.xyz/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)
Vous pouvez émettre directement une requête GET sur /v3/teams/{teamId}, en utilisant la valeur de serviceUrl comme point de terminaison. La valeur de serviceUrl est stable, mais peut changer. Lorsqu'un nouveau message arrive, votre robot doit vérifier sa valeur stockée pour 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"
}
Une fois que vous avez obtenu les détails de l’équipe, vous pouvez obtenir la liste des canaux dans une équipe. Pour récupérer des informations sur une liste de canaux dans une équipe, utilisez les TeamsInfo.GetTeamChannelsAsync API de bot Teams pour C# ou TeamsInfo.getTeamChannels pour les API TypeScript.
Obtenir la liste des canaux dans une équipe
Votre bot peut interroger la liste des canaux d’une équipe.
Remarque
Le nom du canal Général par défaut est retourné en tant que null pour permettre la localisation.
L’ID de canal du canal Général correspond toujours à l’ID d’équipe.
L’exemple de code suivant est utilisé pour obtenir la liste des canaux d’une équipe :
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://zcusa.951200.xyz/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)
Vous pouvez émettre directement une requête GET sur /v3/teams/{teamId}/conversations, en utilisant la valeur de serviceUrl comme point de terminaison. La valeur de serviceUrl est stable, mais peut changer. Lorsqu'un nouveau message arrive, votre robot doit vérifier sa valeur stockée pour serviceUrl.
Pour obtenir des exemples complets illustrant la fonctionnalité, consultez les exemples Teams suivants pour Bot Framework :
Exemple de nom
Description
.NET
Node.js
Python
Manifeste
Bot de conversation Teams
Cet exemple montre comment utiliser différents événements de conversation de bot disponibles dans Bot Framework v4 pour l’étendue personnelle et teams.
La source de ce contenu se trouve sur GitHub, où vous pouvez également créer et examiner les problèmes et les demandes de tirage. Pour plus d’informations, consultez notre guide du contributeur.