Microsoft Teams ボットのコンテキストを取得する

  • [アーティクル]

重要

この記事は、v3 Bot Framework SDK に基づいています。 SDK の現在のドキュメント バージョン 4.6 以降をお探しの場合は、「 会話ボット 」セクションを参照してください。

ボットは、ユーザー プロファイルなど、チームまたはチャットに関する追加のコンテキストにアクセスできます。 この情報は、ボットの機能を強化し、よりパーソナライズされたエクスペリエンスを提供するために使用できます。

注:

  • Microsoft Teams固有のボット API には、Bot Builder SDK 用の拡張機能を通じて最適にアクセスできます。
  • C# または .NET の場合は、 Microsoft.Bot.Connector.Teams NuGet パッケージをダウンロードします。
  • Node.js 開発のために、Bot Builder for Teams 機能が Bot Framework SDK v4.6 に組み込まれています。

チーム名簿を取得する

ボットは、チーム メンバーとその基本的なプロファイルの一覧を照会できます。 基本的なプロファイルには、Teams ユーザー ID と、名前やオブジェクト ID などの Microsoft Entra 情報が含まれます。 この情報を使用して、ユーザー ID を関連付けることができます。 たとえば、Microsoft Entra 資格情報を使用してタブにログインしたユーザーがチーム メンバーであるかどうかを確認します。

REST API の例

serviceUrl値をエンドポイントとして使用して、/conversations/{teamId}/members/で GET 要求を直接発行します。

teamIdは、次のシナリオでボットが受け取るアクティビティ ペイロードのchanneldata オブジェクトにあります。

注:

  • API を呼び出すときは、常にチーム ID を使用します。
  • serviceUrl値は安定している傾向がありますが、変更される可能性があります。 新しいメッセージが到着したら、ボットは格納されている 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 の例

Team.Idを使用してGetConversationMembersAsyncを呼び出して、ユーザー ID の一覧を返します。 GetConversationMembersAsyncを呼び出して、プロパティuserRoleユーザーとして値を返します。

// 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 または TypeScript の例


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

個人用チャットまたはグループ チャットでユーザー プロファイルまたは名簿をフェッチする

任意の個人用チャットの API 呼び出しを行って、ボットとチャットしているユーザーのプロファイル情報を取得できます。

API 呼び出し、SDK メソッド、応答オブジェクトは、チーム名簿のフェッチと同じです。 唯一の違いは、teamIdではなくconversationIdを渡すことです。

チーム内のチャネルの一覧を取得する

ボットは、チーム内のチャネルのリストをクエリできます。

注:

  • ローカリゼーションを可能にするために、既定の一般チャネルの名前が null として返されます。
  • 一般チャネルのチャネル ID は、常にチーム ID と一致します。

REST API の例

serviceUrl値をエンドポイントとして使用して、/teams/{teamId}/conversations/で GET 要求を直接発行します。

teamIdの唯一のソースは、チーム コンテキストからのメッセージです。 メッセージは、ユーザーからのメッセージか、ボットがチームに追加されたときにボットが受け取るメッセージのいずれかです。 詳細については、「 チームに追加されたボットまたはユーザー」を参照してください。

注:

serviceUrl値は安定している傾向がありますが、変更される可能性があります。 新しいメッセージが到着したら、ボットは格納されている 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 の例

次の例では、Bot Builder SDK for .NET の Teams 拡張機能からのFetchChannelList呼び出しを使用します。

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

Node.js の例

次の例では、Bot Builder SDK for Node.jsの Teams 拡張機能からのfetchChannelList呼び出しを使用します。

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

ボット コンテキストで clientInfo を取得する

ボットのアクティビティ内で clientInfo をフェッチできます。 clientInfo には、次のプロパティが含まれています。

  • Locale
  • 国
  • プラットフォーム
  • タイムゾーン

JSON の例

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

C# の例

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

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

関連項目

Bot Framework サンプル。