Bot Framework の ID フィールドID fields in the Bot Framework

適用対象: SDK v4APPLIES TO: SDK v4

このガイドでは、Bot Framework に存在する ID フィールドの特性について説明します。This guide describes the characteristics of ID fields in the Bot Framework.

チャネル IDChannel ID

各 Bot Framework チャネルは一意の ID で識別されます。Every Bot Framework channel is identified by a unique ID.

例: "channelId": "slack"Example: "channelId": "slack"

チャネル ID は、その他の ID の名前空間として機能します。Channel IDs serve as namespaces for other IDs. Bot Framework プロトコルのランタイム呼び出しは、チャネルのコンテキスト内で行われる必要があります。チャネルによって、通信時に使用される会話およびアカウント ID に意味が与えられます。Runtime calls in the Bot Framework protocol must take place within the context of a channel; the channel gives meaning to the conversation and account IDs used when communicating.

規則により、チャネル ID はすべて小文字になります。By convention all channel IDs are lowercase. チャネルにより、生成されるチャネル ID の大文字と小文字の一貫性が保証されます。したがって、ボットでは序数に基づく比較を使用して、等価性を確立することができます。Channels guarantee that the channel IDs they emit have consistent casing, and thus bots may use ordinal comparisons to establish equivalence.

チャネル ID の規則Rules for channel IDs

  • チャネル ID には大文字と小文字の区別があります。Channel IDs are case-sensitive.

ボット ハンドルBot Handle

Azure Bot Service に登録されているボットにはそれぞれボット ハンドルがあります。Every bot that has been registered with the Azure Bot Service has a bot handle.

例: FooBotExample: FooBot

ボット ハンドルは、オンラインの Azure Bot Service へのボットの登録を表します。A bot handle represents a bot's registration with the online Azure Bot Service. この登録は HTTP Webhook のエンドポイントと、チャネルへの登録に関連付けられています。This registration is associated with an HTTP webhook endpoint and registrations with channels.

Azure Bot Service では、ボット ハンドルの一意性が確保されます。The Azure Bot Service ensures uniqueness of bot handles. Azure portal では大文字と小文字を区別しない一意性の確認が行われます (つまり、大文字と小文字にバリエーションがあるボット ハンドルが単一のハンドルとして扱われる) が、これは Azure portal ポータルの特性であり、ボット ハンドル自体の特性とは限りません。The Azure portal performs a case-insensitive uniqueness check (meaning that case variations of bot handle are treated as a single handle) although this is a characteristic of the Azure portal, and not necessarily the bot handle itself.

ボット ハンドルの規則Rules for bot handles

  • ボット ハンドルは Bot Framework 内で一意のものです (大文字と小文字は区別されない)。Bot handles are unique (case-insensitive) within the Bot Framework.

アプリケーション IDApp ID

Azure Bot Service に登録されているボットにはそれぞれアプリ ID があります。Every bot that has been registered with the Azure Bot Service has an App ID.

注意

以前は、アプリは一般的に "MSA アプリ" や "MSA/AAD アプリ" と呼ばれていました。Previously, apps were commonly referred to as "MSA Apps" or "MSA/AAD Apps." 現在、アプリはより一般的に単に "アプリ" と呼ばれますが、一部のプロトコル要素では永続的に "MSA アプリ" と呼ばれる可能性があります。Apps are now more commonly referred to simply as "apps", but some protocol elements may refer to apps as "MSA Apps" in perpetuity.

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

各アプリは ID チームのアプリ ポータルへの登録を表し、Bot Framework ランタイム プロトコル内のサービス間識別メカニズムとして機能します。An app represents a registration with the Identity team's App portal, and serves as the service-to-service identity mechanism within the Bot Framework runtime protocol. アプリには、Web サイト、モバイル アプリケーション、デスクトップ アプリケーションなど、ボット以外の他の関連付けがある場合があります。Apps may have other non-bot associations, such as websites and mobile/desktop applications.

登録されている各ボットにはアプリが 1 つだけあります。Every registered bot has exactly one app. ボットに関連付けられているアプリをボット所有者が個別に変更することはできませんが、少数の例外的な場合において、Bot Framework チームで変更することができます。Although it's not possible for a bot owner to independently change which app is associated with their bot, the Bot Framework team can do so in a small number of exceptional cases.

ボットとチャネルではアプリ ID を使用して、登録されたボットを一意に識別する場合があります。Bots and channels may use app IDs to uniquely identify a registered bot.

アプリケーション ID は必ず GUID となります。App IDs are guaranteed to be GUIDs. アプリケーション ID は大文字と小文字を区別せずに比較する必要があります。App IDs should be compared without case sensitivity.

アプリ ID の規則Rules for app IDs

  • アプリケーション ID は Microsoft アプリ プラットフォーム内で一意のものです (GUID と比較)。App IDs are unique (GUID comparison) within the Microsoft App platform.
  • 各ボットには対応するアプリが 1 つだけあります。Every bot has exactly one corresponding app.
  • ボットが関連付けられるアプリを変更するには、Bot Framework チームの支援が必要です。Changing which app a bot is associated with requires the assistance of the Bot Framework team.

チャネル アカウントChannel Account

ボットとユーザーのアカウントはそれぞれ各チャネル内に存在します。Every bot and user has an account within each channel. アカウントには識別子 (id) とその他の有益なボットの非構造データ (オプション名など) が含まれます。The account contains an identifier (id) and other informative bot non-structural data, like an optional name.

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

このアカウントは、メッセージが送受信される可能性のあるチャネル内のアドレスを示しています。This account describes the address within the channel where messages may be sent and received. 場合によっては、これらの登録が単一サービス (Facebook など) 内に存在します。In some cases, these registrations exist within a single service (e.g., Facebook). 多くのシステム (メール アドレスや電話番号) 間で登録される場合もあります。In others, they are registered across many systems (email addresses, phone numbers). 匿名チャネル (Web チャットなど) では、登録は一時的なものである場合があります。In more anonymous channels (e.g., Web Chat), the registration may be ephemeral.

チャネル アカウントはチャネル内で入れ子になります。Channel accounts are nested within channels. たとえば、Facebook アカウントは単なる数字です。A Facebook account, for example, is simply a number. この数字には他のチャネルでは異なる意味がある場合があり、すべてのチャネルの外部では意味はありません。This number may have a different meaning in other channels, and it doesn't have meaning outside all channels.

チャネル アカウントと (実際の) ユーザー間の関係は、各チャネルに関連付けられている規則によって異なります。The relationship between channel accounts and users (actual people) depends on conventions associated with each channel. たとえば、SMS 番号は通常、一定期間において 1 人のユーザーを指し、その期間が過ぎると、この番号は他のユーザーに転送される場合があります。For example, an SMS number typically refers to one person for a period of time, after which the number may be transferred to someone else. これに対して、Facebook アカウントは通常、永続的に 1 人のユーザーを指しますが、Facebook アカウントを 2 人のユーザーが共有することは珍しくありません。Conversely, a Facebook account typically refers to one person in perpetuity, although it is not uncommon for two people to share a Facebook account.

ほとんどのチャネルでは、チャネル アカウントは、メッセージを配信できるメールボックスのようなものと考えるのが妥当です。In most channels, it's appropriate to think of a channel account as a kind of mailbox where messages can be delivered. ほとんどのチャネルでは複数のアドレスを単一のメールボックスにマップできるのが一般的です。たとえば、"jdoe@contoso.com" と "john.doe@service.contoso.com" は同じ受信トレイに解決されます。It's typical for most channels to allow multiple address to map to a single mailbox; for example, "jdoe@contoso.com" and "john.doe@service.contoso.com" may resolve to the same inbox. 一部のチャネルではさらに一歩先を行き、アクセスしているボットに基づいてアカウントのアドレスが変更されます。たとえば、Facebook ではユーザー ID を変更し、各ボットでメッセージの送受信用に異なるアドレスを利用できるようにします。Some channels go a step further and alter the account's address based on which bot is accessing it; for example, Facebook alters user IDs so every bot has a different address for sending and receiving messages.

場合によってはアドレス間の同等性を確立することはできますが、メールボックス間やユーザー間の同等性を確立するには、チャネル内の規則についての知識が必要になり、多くの場合、確立することはできません。While it's possible in some cases to establish equivalency between addresses, establishing equivalency between mailboxes and equivalency between people requires knowledge of the conventions within the channel, and is in many cases not possible.

ボットに送信されるアクティビティの recipient フィールドを通じて、そのチャネル アカウント アドレスがボットに通知されます。A bot is informed of its channel account address via the recipient field on activities sent to the bot.

チャネル アカウントの規則Rules for channel accounts

  • チャネル アカウントはそれに関連付けられたチャネル内でのみ意味を持ちます。Channel accounts have meaning only within their associated channel.
  • 複数の ID が同じアカウントに解決される可能性があります。More than one ID may resolve to the same account.
  • 2 つの ID が同じであることを確立するために、序数に基づく比較を使用できます。Ordinal comparison may be used to establish that two IDs are the same.
  • 通常、2 つの異なる ID が同じアカウント、ボットまたはユーザーに解決されるかどうかを識別するために使用できる比較はありません。There is generally no comparison that can be used to identify whether two different IDs resolve to the same account, bot or person.
  • ID、アカウント、メールボックス、およびユーザーの間の関連付けの安定性はチャネルによって異なります。The stability of associations between IDs, accounts, mailboxes, and people depends on the channel.

会話 IDConversation ID

メッセージは、ID で特定できる、会話のコンテキストで送受信されます。Messages are sent and received in the context of a conversation, which is identifiable by ID.

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

会話には、メッセージの交換やその他のアクティビティが含まれます。A conversation contains an exchange of messages and other activities. 各会話に 0 個以上のアクティビティがあり、アクティビティはそれぞれ 1 つの会話にのみ存在します。Every conversation has zero or more activities, and every activity appears in exactly one conversation. 会話は永続的である場合や、開始と終了が異なる場合があります。Conversations may be perpetual, or may have distinct starts and ends. 会話の作成、変更、終了のプロセスはチャネル内で発生し (つまり、会話はチャネルで認識されている場合に存在する)、これらのプロセスの特性はチャネルによって確立されます。The process of creating, modifying, or ending a conversation occurs within the channel (i.e., a conversation exists when the channel is aware of it) and the characteristics of these processes are established by the channel.

会話内のアクティビティはユーザーとボットによって送信されます。The activities within a conversation are sent by users and bots. 会話に "参加する" ユーザーの定義はチャネルによって異なり、理論的には、存在するユーザー、メッセージを受信したことがあるユーザー、メッセージを送信したユーザーを含めることができます。The definition for which users "participate" in a conversation varies by channel, and can theoretically include present users, users who have ever received a message, users who sent a message.

いくつかのチャネル (たとえば、SMS や、場合によっては他のチャネル) には、1 対 1 の会話に割り当てられている会話 ID がリモート チャネル アカウント ID であるという特質があります。Several channels (e.g., SMS, and possibly others) have the quirk that the conversation ID assigned to a 1:1 conversation is the remote channel account ID. この特質には以下の 2 つの副作用があります。This quirk has two side-effects:

  1. 会話 ID は、それを表示しているユーザーに基づく主観的なものです。The conversation ID is subjective based on who is viewing it. 参加者の A と B が会話している場合、参加者 A は会話 ID が "B" であることを認識し、参加者 B は会話 ID が "A" であることを認識します。If Participants A and B are talking, participant A sees the conversation ID to be "B" and participant B sees the conversation ID to be "A."
  2. ボットにこのチャネル内の複数のチャネル アカウントがある場合 (たとえば、ボットに 2 つの SMS 番号がある場合)、ボットの視野内で会話を一意に識別するには会話 ID では十分ではありません。If the bot has multiple channel accounts within this channel (for example, if the bot has two SMS numbers), the conversation ID is not sufficient to uniquely identify the conversation within the bot's field of view.

したがって、単一ボットの場合でも、会話 ID によって、チャネル内の単一の会話が一意に識別されるとは限りません。Thus, a conversation ID does not necessarily uniquely identify a single conversation within a channel even for a single bot.

会話 ID の規則Rules for conversation IDs

  • 会話はそれに関連付けられたチャネル内でのみ意味を持ちます。Conversations have meaning only within their associated channel.
  • 複数の ID が同じ会話に解決される可能性があります。More than one ID may resolve to the same conversation.
  • 序数の等価性によって、2 つの会話 ID が同じ会話であることが確立されるとは限りませんが、ほとんどの場合、確立されます。Ordinal equality does not necessarily establish that two conversation IDs are the same conversation, although in most cases, it does.

アクティビティ IDActivity ID

アクティビティは Bot Framework プロトコル内で送受信され、これらを特定できる場合があります。Activities are sent and received within the Bot Framework protocol, and these are sometimes identifiable.

例: "id": "5678"Example: "id": "5678"

アクティビティ ID は省略可能であり、後続の API 呼び出し (使用可能な場合) で ID を参照する方法をボットに示すためにチャネルによって使用されます。Activity IDs are optional and employed by channels to give the bot a way to reference the ID in subsequent API calls, if they are available:

  • 特定のアクティビティへの返信Replying to a particular activity
  • アクティビティ レベルでの参加者の一覧に対するクエリの実行Querying for the list of participants at the activity level

確立されているユース ケースはこれ以上ないため、アクティビティ ID の処理に関する追加の規則はありません。Because no further use cases have been established, there are no additional rules for the treatment of activity IDs.