Получение контекста для ленты Microsoft TeamsGet context for your Microsoft Teams bot

Важно!

Статьи, приведенные в этом разделе, основаны на пакете SDK "V3 Bot Framework".The articles in this section are based on the v3 Bot Framework SDK. Если вы ищете текущую документацию (версия 4,6 или более поздняя версия пакета SDK), ознакомьтесь с разделом " беседы Боты ".If you're looking for current documentation (version 4.6 or later of the SDK) see the Conversational Bots section.

Ваш робот может получить доступ к дополнительному контексту для команды или чата, например для профиля пользователя.Your bot can access additional context about the team or chat, such as user profile. Эти сведения можно использовать, чтобы расширить функциональные возможности Bot и предоставить более персонализированный интерфейс.This information can be used to enrich your bot's functionality and provide a more personalized experience.

Примечание

–Для этих специальных API-интерфейсов ленты Microsoft Teams можно получить доступ через свои расширения для пакета SDK для Bot Builder.These Microsoft Teams–specific bot APIs are best accessed through our extensions for the Bot Builder SDK. Для C#/.нет Скачайте наш пакет NuGet Microsoft. Bot. Connector. Teams .For C#/.NET, download our Microsoft.Bot.Connector.Teams NuGet package. Для Node.js разработки функция Ботбуилдер для Microsoft Teams встроена в пакет SDK для Bot Framework версии 4.6.For Node.js development, the BotBuilder for Microsoft Teams functionality has been incorporated into the Bot Framework SDK as of v4.6.

Получение списка командFetching the team roster

Ваш робот может запросить список участников группы и их базовые профили, в том числе идентификаторы пользователей Teams и Azure Active Directory (Azure AD), такие как Name и objectId.Your bot can query for the list of team members and their basic profiles, which includes Teams user IDs and Azure Active Directory (Azure AD) information such as name and objectId. Эти сведения можно использовать для сопоставления удостоверений пользователей; Например, чтобы проверить, является ли пользователь, вошедший на вкладку с помощью учетных данных Azure AD, участником команды.You can use this information to correlate user identities; for example, to check whether a user logged into a tab through Azure AD credentials is a member of the team.

Пример API RESTREST API example

Вы можете отправить запрос GET напрямую /conversations/{teamId}/members/ , используя значение в serviceUrl качестве конечной точки.You can directly issue a GET request on /conversations/{teamId}/members/, using the value of serviceUrl as the endpoint.

teamIdМожно найти в channeldata объекте полезных данных действия, который получит ваш почтовый робот в следующих сценариях:The teamId can be found in the channeldata object of the activity payload that your bot receives in the following scenarios:

Примечание

  • Обязательно используйте идентификатор команды при вызове APIMake sure to use the team id when calling the api
  • Значение " serviceUrl является стабильным, но может измениться".The value of serviceUrl tends to be stable but can change. Когда поступает новое сообщение, ваш робот должен проверить сохраненное значение serviceUrl .When a new message arrives, your bot should verify its stored value of serviceUrl.
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.NET example

Call GetConversationMembersAsync using Team.Id для возврата списка идентификаторов пользователей.Call GetConversationMembersAsync using Team.Id to return a list of user IDs.

// 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/ТипескриптNode.js/TypeScript example


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

В этой статье также приведены примеры кода Bot Framework.See also Bot Framework samples.

Получение профиля пользователя или списка в личном или группом чатеFetching user profile or roster in personal or group chat

Вы также можете выполнить один вызов API для любого личного чата, чтобы получить сведения о профиле пользователя в чате.You can also make the same API call for any personal chat to obtain the profile information of the user chatting with your bot.

Вызовы API и методы SDK идентичны получению списка команд, как и объект Response.The API call and SDK methods are identical to fetching the team roster, as is the response object. Единственное отличие заключается в том, что вместо него передается значение conversationId teamId .The only difference is you pass the conversationId instead of the teamId.

Получение списка каналов в командеFetching the list of channels in a team

Ваш робот может запросить список каналов в команде.Your bot can query the list of channels in a team.

Примечание

  • По умолчанию возвращается имя общего канала, null позволяющее выполнять локализацию.The name of the default General channel is returned as null to allow for localization.
  • Идентификатор канала для общего канала всегда соответствует ИДЕНТИФИКАТОРу группы.The channel ID for the General channel always matches the team ID.

Пример API RESTREST API example

Вы можете отправить запрос GET напрямую /teams/{teamId}/conversations/ , используя значение в serviceUrl качестве конечной точки.You can directly issue a GET request on /teams/{teamId}/conversations/, using the value of serviceUrl as the endpoint.

Единственный источник teamId — это сообщение от контекста команды — либо сообщение от пользователя, либо сообщение, которое поступает от пользователя Bot при его добавлении в команду (см. пользователь или пользователь, добавленный в команду).The only source for teamId is a message from the team context - either a message from a user or the message that your bot receives when it is added to a team (see Bot or user added to a team).

Примечание

Значение " serviceUrl является стабильным, но может измениться".The value of serviceUrl tends to be stable but can change. Когда поступает новое сообщение, ваш робот должен проверить сохраненное значение serviceUrl .When a new message arrives, your bot should verify its stored value of serviceUrl.

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.NET example

В следующем примере используется FetchChannelList вызов из расширений Microsoft Teams для пакета SDK построителя построителя для .NET:The following example uses the FetchChannelList call from the Microsoft Teams extensions for the Bot Builder SDK for .NET:

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

Пример Node.jsNode.js example

В следующем примере используется fetchChannelList вызов из расширений Microsoft Teams для пакета SDK построителя для Node.js.The following example uses fetchChannelList call from the Microsoft Teams extensions for the Bot Builder SDK for Node.js.

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