Abrufen des Kontexts für Ihren Microsoft Teams-Bot

  • Artikel

Wichtig

Dieser Artikel basiert auf dem Bot Framework SDK v3. Wenn Sie nach der aktuellen Dokumentationsversion 4.6 oder höher des SDK suchen, lesen Sie den Abschnitt Konversationsbots .

Ihr Bot kann auf zusätzlichen Kontext zum Team oder Chat zugreifen, z. B. auf das Benutzerprofil. Diese Informationen können verwendet werden, um die Funktionalität Ihres Bots zu erweitern und eine persönlichere Erfahrung zu bieten.

Hinweis

  • Auf Microsoft Teams-spezifische Bot-APIs kann am besten über unsere Erweiterungen für das Bot Builder SDK zugegriffen werden.
  • Laden Sie für C# oder .NET das NuGet-Paket Microsoft.Bot.Connector.Teams herunter.
  • Für Node.js Entwicklung ist die Bot Builder für Teams-Funktionalität in das Bot Framework SDK v4.6 integriert.

Abrufen der Teamliste

Ihr Bot kann die Liste der Teammitglieder und deren Basisprofile abfragen. Die grundlegenden Profile enthalten Teams-Benutzer-IDs und Microsoft Entra Informationen wie Name und Objekt-ID. Sie können diese Informationen verwenden, um Benutzeridentitäten zu korrelieren. Überprüfen Sie beispielsweise, ob ein Benutzer, der sich über Microsoft Entra Anmeldeinformationen bei einer Registerkarte angemeldet hat, ein Teammitglied ist.

REST-API-Beispiel

Direktes Ausgeben einer GET-Anforderung für /conversations/{teamId}/members/unter Verwendung des serviceUrl Werts als Endpunkt.

Befindet teamId sich im channeldata -Objekt der Aktivitätsnutzlast, die Ihr Bot in den folgenden Szenarien empfängt:

Hinweis

  • Verwenden Sie beim Aufrufen der API immer die Team-ID.
  • Der serviceUrl Wert ist tendenziell stabil, kann sich aber ändern. Wenn eine neue Nachricht eingeht, muss Ihr Bot den gespeicherten serviceUrl Wert überprüfen.
GET /v3/conversations/19:ja0cu120i1jod12j@skype.net/members

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"
}, {
    "id": "29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk",
    "objectId": "76b0b09f-d410-48fd-993e-84da521a597b",
    "givenName": "John",
    "surname": "Patterson",
    "email": "johnp@fabrikam.com",
    "userPrincipalName": "johnp@fabrikam.com"
}, {
    "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"
}]

.NET-Beispiel

Rufen Sie GetConversationMembersAsync mit Team.Id auf, um eine Liste von Benutzer-IDs zurückzugeben. Der Aufruf GetConversationMembersAsync zum Abrufen userRole der Eigenschaft gibt den Wert als Benutzer zurück.

// Fetch the members in the current conversation
var connector = new ConnectorClient(new Uri(context.Activity.ServiceUrl));
var teamId = context.Activity.GetChannelData<TeamsChannelData>().Team.Id;
var members = await connector.Conversations.GetConversationMembersAsync(teamId);

// Concatenate information about all members into a string
var sb = new StringBuilder();
foreach (var member in members.AsTeamsChannelAccounts())
{
    sb.AppendFormat(
        "GivenName = {0}, TeamsMemberId = {1}",
        member.Name, member.Id);

    sb.AppendLine();
}

// Post the member info back into the conversation
await context.PostAsync($"People in this conversation: {sb.ToString()}");

Node.js- oder TypeScript-Beispiel


[...]
import * as builder from "botbuilder";
[...]

var teamId = session.message.sourceEvent.team.id;
connector.fetchMembers(
  (<builder.IChatConnectorAddress>session.message.address).serviceUrl,
  teamId,
  (err, result) => {
    if (err) {
      session.endDialog('There is some error');
    }
    else {
      session.endDialog('%s', JSON.stringify(result));
    }
  }
);

Abrufen eines Benutzerprofils oder einer Liste im persönlichen Chat oder Gruppenchat

Sie können den API-Aufruf für jeden persönlichen Chat durchführen, um die Profilinformationen des Benutzers abzurufen, der mit Ihrem Bot chatt.

Der API-Aufruf, die SDK-Methoden und das Antwortobjekt sind mit dem Abrufen der Teamliste identisch. Der einzige Unterschied besteht darin, dass Sie anstelle conversationId von teamIdübergeben.

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.

REST-API-Beispiel

Direktes Ausgeben einer GET-Anforderung für /teams/{teamId}/conversations/unter Verwendung des serviceUrl Werts als Endpunkt.

Die einzige Quelle für teamId ist eine Nachricht aus dem Teamkontext. Die Nachricht ist entweder eine Nachricht von einem Benutzer oder die Nachricht, die Ihr Bot empfängt, wenn sie einem Team hinzugefügt wird. Weitere Informationen finden Sie unter Hinzufügen eines Bots oder Benutzers zu einem Team.

Hinweis

Der serviceUrl Wert ist tendenziell stabil, kann sich aber ändern. Wenn eine neue Nachricht eingeht, muss Ihr Bot den gespeicherten serviceUrl Wert ü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"
    }]
}

.NET-Beispiel

Im folgenden Beispiel wird der FetchChannelList Aufruf aus den Teams-Erweiterungen für das Bot Builder SDK für .NET verwendet:

ConversationList channels = client.GetTeamsConnectorClient().Teams.FetchChannelList(activity.GetChannelData<TeamsChannelData>().Team.Id);

Node.js Beispiel

Im folgenden Beispiel wird der Aufruf aus den Teams-Erweiterungen für das Bot Builder SDK für Node.jsverwendetfetchChannelList:

var teamId = session.message.sourceEvent.team.id;
connector.fetchChannelList(
  (session.message.address).serviceUrl,
  teamId,
  (err, result) => {
    if (err) {
      session.endDialog('There is an error');
    }
    else {
      session.endDialog('%s', JSON.stringify(result));
    }
  }
);

Abrufen von clientInfo in Ihrem Botkontext

Sie können die clientInfo in der Aktivität Ihres Bots abrufen. ClientInfo enthält die folgenden Eigenschaften:

  • Locale
  • Land
  • Plattform
  • Zeitzone

JSON-Beispiel

[
    {
        "type": "clientInfo",
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "Asia/Calcutta"
    }
]

C#-Beispiel

var connector = new ConnectorClient(new Uri(context.Activity.ServiceUrl));

{
    var clientinfo = context.Activity.Entities[0];
    await context.PostAsync($"ClientInfo: clientinfo ");
}

Siehe auch

Bot Framework-Beispiele.