Microsoft Teams-Kontext für Ihren Bot erhalten

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf Version 4.6 und höheren Versionen des Bot Framework SDK. Wenn Sie nach Dokumentation zu früheren Versionen suchen, lesen Sie den Abschnitt bots – v3 SDK im Ordner Legacy SDKs der Dokumentation.

Ein Bot kann auf zusätzliche Kontextdaten zu einem Team oder Chat zugreifen, in dem er installiert ist. Diese Informationen können verwendet werden, um die Funktionalität des Bots zu erweitern und eine persönlichere Benutzererfahrung zu bieten.

Abrufen der Mitgliederliste oder des Benutzerprofils

Ihr Bot kann die Liste der Mitglieder und deren grundlegende Benutzerprofile abfragen, einschließlich Teams-Benutzer-IDs und Microsoft Entra Informationen wie Name und ObjectId. Sie können diese Informationen verwenden, um Benutzeridentitäten zu korrelieren. Um beispielsweise zu überprüfen, ob ein Benutzer, der sich über Microsoft Entra Anmeldeinformationen bei einer Registerkarte angemeldet hat, mitglied des Teams ist. Für das Abrufen von Unterhaltungsmitgliedern hängt die minimale oder maximale Seitengröße von der Implementierung ab. Seitengrößen unter 50 werden als 50 behandelt, und größere als 500 sind auf 500 begrenzt. Selbst wenn Sie die nicht ausgelagerte Version verwenden, ist sie in großen Teams unzuverlässig und darf nicht verwendet werden. Weitere Informationen finden Sie unter Änderungen an Microsoft Teams-Bot-APIs zum Abrufen von Team- oder Chatmitgliedern.

Hinweis

• Die Paginierung ist in einem Team und einem Kanal verfügbar.
• Die Paginierung wird in Chats nicht unterstützt. Bei Chats wird immer die gesamte Liste zurückgegeben.

Im folgenden Beispielcode wird der ausgelagerte Endpunkt zum Abrufen der Teilnehmerliste verwendet:

C#

• SDK-Referenz

• Beispielcodereferenz

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);
     }
}

TypeScript

• SDK-Referenz

• Beispielcodereferenz

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

Python

• SDK-Referenz

async def _show_members(
    self, turn_context: TurnContext
):
    # Get a conversationMember from a team.
    members = await TeamsInfo.get_team_members(turn_context)

JSON

Sie können eine GET-Anforderung direkt auf /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken} ausgeben, indem Sie den Wert von serviceUrl als Endpunkt verwenden. Der Wert von serviceUrl ist stabil, kann sich aber ändern. Wenn eine neue Nachricht eintrifft, sollte Ihr Bot den gespeicherten Wert für serviceUrl überprüfen. Die Antwortnutzlast gibt auch an, ob der Benutzer ein regulärer oder anonymer Benutzer ist.

GET /v3/conversations/19:meeting_N2QzYTA3YmItYmMwOC00OTJmLThkYzMtZWMzZGU0NGIyZGI0@thread.v2/pagedmembers?pageSize=100&continuationToken=asdfasdfalkdsjfalksjdf

Response body
{
   "continuationToken":"asdfqwerueiqpiewr",
   "members":[
      {
         "id":"29:1GcS4EyB_oSI8A88XmWBN7NJFyMqe3QGnJdgLfFGkJnVelzRGos0bPbpsfJjcbAD22bmKc4GMbrY2g4JDrrA8vM06X1-cHHle4zOE6U4ttcc",
         "name":"Anon1 (Guest)",
         "tenantId":"29:1UX7p8Fkx7p93MZlBFS71swTB9juQOCfnXf2L3wxOUITCcIGpFcRX-JiFjLDVZhxGpEfzSTGNsZeEyTKr1iu3Vw",
         "userRole":"anonymous"
      },
      {
         "id":"29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk",
         "objectId":"76b0b09f-d410-48fd-993e-84da521a597b",
         "givenName":"John",
         "surname":"Patterson",
         "email":"johnp@fabrikam.com",
         "userPrincipalName":"johnp@fabrikam.com",
         "tenantId":"29:1UX7p8Fkx7p93MZlBFS71swTB9juQOCfnXf2L3wxOUITCcIGpFcRX-JiFjLDVZhxGpEfzSTGNsZeEyTKr1iu3Vw",
         "userRole":"user"
      },
      {
         "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",
         "tenantId":"29:1UX7p8Fkx7p93MZlBFS71swTB9juQOCfnXf2L3wxOUITCcIGpFcRX-JiFjLDVZhxGpEfzSTGNsZeEyTKr1iu3Vw",
         "userRole":"user"
      }
   ]
}

Nachdem Sie die Teilnehmerliste oder das Benutzerprofil abgerufen haben, können Sie Details zu einem einzelnen Mitglied abrufen. Um Informationen zu einem oder mehreren Mitgliedern eines Chats oder Teams abzurufen, verwenden Sie derzeit die Microsoft Teams-Bot-APIs TeamsInfo.GetMembersAsync für C# oder TeamsInfo.getMembers für TypeScript-APIs.

Abrufen von Details zu einzelnen Mitgliedern

Sie können die Details eines bestimmten Benutzers auch mithilfe seiner Teams-Benutzer-ID, des UPN oder Microsoft Entra-Objekt-ID abrufen.

Der folgende Beispielcode wird verwendet, um Details zu einzelnen Mitgliedern abzurufen:

C#

• SDK-Referenz

• Beispielcodereferenz

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);
    }
}

TypeScript

• SDK-Referenz

• Beispielcodereferenz

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

Python

• SDK-Referenz

• Beispielcodereferenz

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)

JSON

Sie können eine GET-Anforderung direkt auf /v3/conversations/{conversationId}/members/{userId} ausgeben, indem Sie den Wert von serviceUrl als Endpunkt verwenden. Der Wert von serviceUrl ist stabil, kann sich aber ändern. Wenn eine neue Nachricht eintrifft, sollte Ihr Bot den gespeicherten Wert für serviceUrl überprüfen. Dies kann für normale und anonyme Benutzer verwendet werden.

Es folgt das Antwortbeispiel für normale Benutzer:

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"
}

Es folgt das Antwortbeispiel für anonyme Benutzer:

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"
}

Nachdem Sie Details zu einem einzelnen Mitglied erhalten haben, können Sie Details des Teams abrufen. Verwenden Sie derzeit zum Abrufen von Informationen für ein Team die Teams-Bot-APIs TeamsInfo.GetMemberDetailsAsync für C# oder TeamsInfo.getTeamDetails für TypeScript.

Abrufen von Teamdetails

Bei der Installation in einem Team kann Ihr Bot Metadaten zu diesem Team abfragen, einschließlich der Microsoft Entra Gruppen-ID.

Der folgende Beispielcode wird verwendet, um die Details des Teams abzurufen:

C#

• SDK-Referenz

• Beispielcodereferenz

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

TypeScript

• SDK-Referenz

• Beispielcodereferenz

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

Python

SDK-Referenz

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)

JSON

Sie können eine GET-Anforderung direkt auf /v3/teams/{teamId} ausgeben, indem Sie den Wert von serviceUrl als Endpunkt verwenden. Der Wert von serviceUrl ist stabil, kann sich aber ändern. Wenn eine neue Nachricht eintrifft, sollte Ihr Bot den gespeicherten Wert für serviceUrl überprüfen.

GET /v3/teams/19:ja0cu120i1jod12j@skype.net

Response body
{
    "id": "29:1GcS4EyB_oSI8A88XmWBN7NJFyMqe3QGnJdgLfFGkJnVelzRGos0bPbpsfJjcbAD22bmKc4GMbrY2g4JDrrA8vM06X1-cHHle4zOE6U4ttcc",
    "name": "The Team Name",
    "aadGroupId": "02ce3874-dd86-41ba-bddc-013f34019978"
}

Nachdem Sie Details des Teams erhalten haben, können Sie die Liste der Kanäle in einem Team abrufen. Verwenden Sie derzeit zum Abrufen von Informationen für eine Liste von Kanälen in einem Team die Teams-Bot-APIs TeamsInfo.GetTeamChannelsAsync für C# oder TeamsInfo.getTeamChannels für TypeScript-APIs.

Abrufen der Liste der Kanäle in einem Team

Ihr Bot kann die Liste der Kanäle in einem Team abfragen.

Hinweis

• Der Name des Standardkanals "Allgemein" wird als null zurückgegeben, um die Lokalisierung zu ermöglichen.
• Die Kanal-ID für den Kanal "Allgemein" stimmt immer mit der Team-ID überein.

Der folgende Beispielcode wird verwendet, um die Liste der Kanäle in einem Team abzurufen:

C#

• SDK-Referenz

• Beispielcodereferenz

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

TypeScript

SDK-Referenz

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

Python

SDK-Referenz

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)

JSON

Sie können eine GET-Anforderung direkt auf /v3/teams/{teamId}/conversations ausgeben, indem Sie den Wert von serviceUrl als Endpunkt verwenden. Der Wert von serviceUrl ist stabil, kann sich aber ändern. Wenn eine neue Nachricht eintrifft, sollte Ihr Bot den gespeicherten Wert für serviceUrl überprüfen.

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"
    }]
}

Teams-Botbeispiele

Codebeispiel

Vollständige Arbeitsbeispiele zur Veranschaulichung der Funktionalität finden Sie in den folgenden Teams-Beispielen für Bot Framework:

Beispielname	Beschreibung	.NET	Node.js	Python	Manifest
Teams-Unterhaltungsbot	In diesem Beispiel wird gezeigt, wie Verschiedene Botunterhaltungsereignisse verwendet werden, die in Bot Framework v4 für den persönlichen Bereich und den Teams-Bereich verfügbar sind.	View	View	View	Anzeigen
Authentifizierung mit OAuthPrompt	Dieses Beispiel zeigt die Authentifizierung und grundlegendes Messaging in Bot Framework v4.	View	View	View	Anzeigen
Teams-Dateiupload	In diesem Beispiel wird gezeigt, wie Dateien mit einem Bot in einer 1:1-Konversation verwendet werden.	View	View	View	Anzeigen
Dialog (in TeamsJS v1.x als Aufgabenmodul bezeichnet)	In diesem Beispiel wird gezeigt, wie Sie ein Dialogfeld und Werte aus Karten darin für eine Nachrichtenerweiterung verwenden.	View	View	View	View
Starten eines neuen Threads in einem Kanal	In diesem Beispiel wird die Verwendung eines neuen Threads in einem Kanal mithilfe eines Bots veranschaulicht.	View	View	View	Anzeigen
Lokalisierung von Teams-Apps	In diesem Beispiel wird gezeigt, wie Sie die Lokalisierung von Teams-Apps mithilfe eines Bots und einer Registerkarte verwenden.	View	View	–	Anzeigen

Nächster Schritt

Senden und Empfangen von Dateien mithilfe eines Bots

Siehe auch

• Erstellen von Bots für Teams
• Dialogs
• Authentifizieren von Benutzern in Microsoft Teams
• Bot-Aktivitätenhandler
• Lokalisieren IhrerApp
• Abrufen der Profilfoto eines Benutzers, einer Gruppe, eines Teams oder eines Outlook-Kontakts