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

重要

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

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

注

  • Microsoft Teams 固有のボット API には、Bot Builder SDK の拡張機能を通じて最適にアクセスできます。
  • C# または .NET の場合は、 Microsoft.Bot.Connector.Teams NuGet パッケージをダウンロードします。
  • Node.js 開発のために、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値を userとして返します。

// 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 例

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

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 には、次のプロパティが含まれています。

  • ロケール
  • 国
  • プラットフォーム
  • タイムゾーン

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 サンプル。

  • Last updated on