次の方法で共有


Bot Framework の ID フィールド

適用対象: SDK v4

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

チャネル ID

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

例: "channelId": "slack"

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

慣例により、すべてのチャネル ID は小文字です。 チャネルは、それらが出力するチャネル ID の大文字と小文字の区別が一貫していることを保証するため、ボットは序数比較を使用して等価性を確立できます。

チャネル ID の規則

  • チャネル ID では大文字と小文字が区別されます。

ボット ハンドル

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

例: FooBot

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

Azure AI Bot Service は、ボット ハンドルの一意性を保証します。 Azure portal では、大文字と小文字を区別しない一意性チェック (つまり、ボット ハンドルの大文字と小文字のバリエーションは 1 つのハンドルとして扱われます) が実行されますが、これは Azure portal の特性であり、必ずしもボットが自身を処理するとは限りません。

ボット ハンドルのルール

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

アプリ ID

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

手記

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

例: "msaAppId": "00001111-aaaa-2222-bbbb-3333cccc4444"

アプリは ID チームのアプリ ポータルへの登録を表し、Bot Framework ランタイム プロトコル内のサービス間 ID メカニズムとして機能します。 アプリには、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.com" と "john.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 の処理に関する追加の規則はありません。