Bot Framework の ID フィールド

  • [アーティクル]

適用対象: SDK v4

このガイドでは、Bot Framework に存在する ID フィールドの特性について説明します。

チャネル ID

各 Bot Framework チャネルは一意の ID で識別されます。

例: "channelId": "slack"

チャネル ID は、その他の ID の名前空間として機能します。 Bot Framework プロトコルのランタイム呼び出しは、チャネルのコンテキスト内で行われる必要があります。チャネルによって、通信時に使用される会話およびアカウント ID に意味が与えられます。

規則により、チャネル ID はすべて小文字になります。 チャネルにより、生成されるチャネル ID の大文字と小文字の一貫性が保証されます。したがって、ボットでは序数に基づく比較を使用して、等価性を確立することができます。

チャネル ID の規則

  • チャネル ID には大文字と小文字の区別があります。

ボット ハンドル

Azure AI Bot Serviceに登録されているすべてのボットには、ボット ハンドルがあります。

例: FooBot

ボット ハンドルは、オンラインの Azure AI Bot Serviceに対するボットの登録を表します。 この登録は HTTP Webhook のエンドポイントと、チャネルへの登録に関連付けられています。

Azure AI Bot Serviceにより、ボット ハンドルの一意性が確保されます。 Azure portal では大文字と小文字を区別しない一意性の確認が行われます (つまり、大文字と小文字にバリエーションがあるボット ハンドルが単一のハンドルとして扱われる) が、これは Azure portal ポータルの特性であり、ボット ハンドル自体の特性とは限りません。

ボット ハンドルの規則

  • ボット ハンドルは Bot Framework 内で一意のものです (大文字と小文字は区別されない)。

アプリケーション ID

Azure AI Bot Serviceに登録されているすべてのボットには、アプリ ID があります。

注意

以前は、アプリは一般に "MSA アプリ" または "MSA/AAD アプリ" と呼ばれていた。アプリは、より一般的に単に "アプリ" と呼ばれるようになりましたが、一部のプロトコル要素では、永続的にアプリを "MSA Apps" と呼ぶ場合があります。

例: "msaAppId": "353826a6-4557-45f8-8d88-6aa0526b8f77"

各アプリは ID チームのアプリ ポータルへの登録を表し、Bot Framework ランタイム プロトコル内のサービス間識別メカニズムとして機能します。 アプリには、Web サイト、モバイル アプリケーション、デスクトップ アプリケーションなど、ボット以外の他の関連付けがある場合があります。

登録されている各ボットにはアプリが 1 つだけあります。 ボット所有者がボットに関連付けられているアプリを個別に変更することはできませんが、Bot Framework チームはいくつかの例外的なケースでこれを行うことができます。

ボットとチャネルではアプリ ID を使用して、登録されたボットを一意に識別する場合があります。

アプリケーション ID は必ず GUID となります。 アプリケーション ID は大文字と小文字を区別せずに比較する必要があります。

アプリ ID の規則

  • アプリケーション ID は Microsoft アプリ プラットフォーム内で一意のものです (GUID と比較)。
  • 各ボットには対応するアプリが 1 つだけあります。
  • ボットが関連付けられるアプリを変更するには、Bot Framework チームの支援が必要です。

チャネル アカウント

ボットとユーザーのアカウントはそれぞれ各チャネル内に存在します。 アカウントには識別子 (id) とその他の有益なボットの非構造データ (オプション名など) が含まれます。

例: "from": { "id": "john.doe@contoso.com", "name": "John Doe" }

このアカウントは、メッセージが送受信される可能性のあるチャネル内のアドレスを示しています。 場合によっては、これらの登録は Facebook などの 1 つのサービス内に存在します。 他のシステムでは、多くのシステム (メール アドレス、電話番号) に登録されています。 Web チャットなど、より匿名のチャネルでは、登録が一時的である可能性があります。

チャネル アカウントはチャネル内で入れ子になります。 たとえば、Facebook アカウントは単なる数字です。 この数字には他のチャネルでは異なる意味がある場合があり、すべてのチャネルの外部では意味はありません。

チャネル アカウントと (実際の) ユーザー間の関係は、各チャネルに関連付けられている規則によって異なります。 たとえば、SMS 番号は通常、1 人のユーザーを指しますが、その番号は他のユーザーに転送される場合があります。 逆に、Facebook アカウントは通常、1 人のユーザーを永続的に指しますが、2 人が Facebook アカウントを共有することは珍しくありません。

ほとんどのチャネルでは、チャネル アカウントは、メッセージを配信できるメールボックスのようなものと考えるのが妥当です。 ほとんどのチャネルでは、複数のアドレスを 1 つのメールボックスにマップすることが一般的です。 たとえば、"" と "jdoe@contoso.comjohn.doe@service.contoso.com" は同じ受信トレイに解決される場合があります。 一部のチャネルでは、さらに一歩進み、アクセスしているボットに基づいてアカウントのアドレスを変更します。 たとえば、Facebook はユーザー ID を変更して、すべてのボットがメッセージの送受信用に異なるアドレスを持つようにします。

場合によってはアドレス間の同等性を確立することはできますが、メールボックス間やユーザー間の同等性を確立するには、チャネル内の規則についての知識が必要になり、多くの場合、確立することはできません。

ボットに送信されるアクティビティの recipient フィールドを通じて、そのチャネル アカウント アドレスがボットに通知されます。

チャネル アカウントの規則

  • チャネル アカウントはそれに関連付けられたチャネル内でのみ意味を持ちます。
  • 複数の ID が同じアカウントに解決される可能性があります。
  • 2 つの ID が同じであることを確立するために、序数に基づく比較を使用できます。
  • 一般に、2 つの異なる ID が同じアカウント、ボット、またはユーザーに解決されるかどうかを識別するために使用できる比較はありません。
  • ID、アカウント、メールボックス、ユーザー間の関連付けの安定性は、チャネルによって異なります。

会話 ID

メッセージは、ID で特定できる、会話のコンテキストで送受信されます。

例: "conversation": { "id": "1234" }

会話には、メッセージの交換やその他のアクティビティが含まれます。 各会話に 0 個以上のアクティビティがあり、アクティビティはそれぞれ 1 つの会話にのみ存在します。 会話は永続的である場合や、開始と終了が異なる場合があります。 会話を作成、変更、または終了するプロセスは、チャネル内で行われます。会話はチャネルが認識している間にのみ存在し、これらのプロセスの特性はチャネルによって確立されます。

会話内のアクティビティはユーザーとボットによって送信されます。 会話に "参加する" ユーザーの定義はチャネルによって異なり、理論的には、存在するユーザー、メッセージを受信したことがあるユーザー、メッセージを送信したユーザーを含めることができます。

SMS や他のチャネルなど、いくつかのチャネルには、1 対 1 の会話に割り当てられた会話 ID がリモート チャネル アカウント ID であるという風変わりな機能があります。 この特質には以下の 2 つの副作用があります。

  1. 会話 ID は、閲覧しているユーザーに基づいて主観的です。 参加者 A と B が話している場合、参加者 A は会話 ID を "B" と見なし、参加者 B は会話 ID を "A" と見なします。
  2. ボットがこのチャネル内に複数のチャネル アカウントを持っている場合 (たとえば、ボットに 2 つの SMS 番号がある場合)、会話 ID では、ボットの視野内で会話を一意に識別するのに十分ではありません。

したがって、会話 ID は、1 つのボットであっても、チャネル内の 1 つの会話を一意に識別するとは限りません。

会話 ID の規則

  • 会話はそれに関連付けられたチャネル内でのみ意味を持ちます。
  • 複数の ID が同じ会話に解決される可能性があります。
  • 序数の等価性は、2 つの会話 ID が同じ会話であることを必ずしも確立するとは限りませんが、ほとんどの場合は同じです。

アクティビティ ID

アクティビティは Bot Framework プロトコル内で送受信され、これらを特定できる場合があります。

例: "id": "5678"

アクティビティ ID は省略可能であり、チャネルによって使用され、ボットが後続の API 呼び出しで ID を参照する方法を提供します (使用可能な場合)。

  • 特定のアクティビティへの返信
  • アクティビティ レベルでの参加者の一覧に対するクエリの実行

確立されているユース ケースはこれ以上ないため、アクティビティ ID の処理に関する追加の規則はありません。