ID-Felder im Bot Framework

GILT FÜR: SDK v4

In diesem Leitfaden werden die Merkmale von ID-Feldern im Bot Framework beschrieben.

Kanal-ID

Jeder Bot Framework-Kanal wird durch eine eindeutige ID identifiziert.

Beispiel: "channelId": "slack"

Kanal-IDs dienen als Namespaces für andere IDs. Laufzeitaufrufe im Bot Framework-Protokoll müssen im Kontext eines Kanals erfolgen; der Kanal gibt den Unterhaltungs- und Konto-IDs bedeutung, die bei der Kommunikation verwendet werden.

Standardmäßig sind alle Kanal-IDs Kleinbuchstaben. Kanäle garantieren, dass die von ihnen ausgegebenen Kanal-IDs eine konsistente Groß-/Kleinschreibung aufweisen, und daher können Bots Ordinalvergleiche verwenden, um Äquivalenz herzustellen.

Regeln für Kanal-IDs

• Bei Kanal-IDs wird die Groß-/Kleinschreibung beachtet.

Bot-Handle

Jeder Bot, der beim Azure AI Bot Service registriert wurde, verfügt über einen Bot-Handle.

Beispiel: FooBot

Ein Bot-Handle stellt die Registrierung eines Bots beim Online-Azure AI Bot-Dienst dar. Diese Registrierung ist einem HTTP-Webhook-Endpunkt und Registrierungen mit Kanälen zugeordnet.

Der Azure AI Bot Service stellt die Eindeutigkeit von Bot-Handles sicher. Das Azure-Portal führt eine Überprüfung der eindeutigen Groß-/Kleinschreibung durch (d. h. die Groß-/Kleinschreibung des Bot-Handles wird als einzelnes Handle behandelt), obwohl dies ein Merkmal des Azure-Portals ist und nicht unbedingt der Bot sich selbst behandelt.

Regeln für Bot-Handles

• Bot-Handles sind eindeutig (Groß-/Kleinschreibung) innerhalb des Bot-Frameworks.

App-ID

Jeder Bot, der beim Azure AI Bot Service registriert wurde, verfügt über eine App-ID.

Anmerkung

Bisher wurden Apps häufig als "MSA Apps" oder "MSA/AAD Apps" bezeichnet. Apps werden jetzt häufiger einfach als "Apps" bezeichnet, aber einige Protokollelemente beziehen sich möglicherweise auf Apps als "MSA-Apps" perPetuity.

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

Eine App stellt eine Registrierung beim App-Portal des Identitätsteams dar und dient als Dienst-zu-Dienst-Identitätsmechanismus innerhalb des Bot Framework-Laufzeitprotokolls. Apps verfügen möglicherweise über andere Nicht-Bot-Zuordnungen, z. B. Websites und Mobile/Desktop-Anwendungen.

Jeder registrierte Bot verfügt über genau eine App. Obwohl es für einen Botbesitzer nicht möglich ist, unabhängig zu ändern, welche App mit ihrem Bot verknüpft ist, kann das Bot Framework-Team dies in einigen Ausnahmefällen tun.

Bots und Kanäle können App-IDs verwenden, um einen registrierten Bot eindeutig zu identifizieren.

App-IDs sind garantiert GUIDs. App-IDs sollten ohne Groß-/Kleinschreibung verglichen werden.

Regeln für App-IDs

• App-IDs sind eindeutig (GUID-Vergleich) innerhalb der Microsoft App-Plattform.
• Jeder Bot verfügt über genau eine entsprechende App.
• Das Ändern der App, der ein Bot zugeordnet ist, erfordert die Unterstützung des Bot Framework-Teams.

Kanalkonto

Jeder Bot und Jeder Benutzer verfügt über ein Konto innerhalb jedes Kanals. Das Konto enthält einen Bezeichner (id) und andere informative Bot-nicht-strukturelle Daten, z. B. einen optionalen Namen.

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

Dieses Konto beschreibt die Adresse innerhalb des Kanals, an den Nachrichten gesendet und empfangen werden können. In einigen Fällen existieren diese Registrierungen in einem einzigen Dienst, z. B. Facebook. In anderen Systemen sind sie in vielen Systemen registriert (E-Mail-Adressen, Telefonnummern). In anonymeren Kanälen, z. B. Web-Chat, kann die Registrierung kurzlebig sein.

Kanalkonten werden in Kanälen geschachtelt. Ein Facebook-Konto ist z. B. einfach eine Nummer. Diese Zahl kann in anderen Kanälen eine andere Bedeutung haben, und sie hat keine Bedeutung außerhalb aller Kanäle.

Die Beziehung zwischen Kanalkonten und Benutzern (tatsächlichen Personen) hängt von den Konventionen ab, die mit den einzelnen Kanälen verknüpft sind. Beispielsweise bezieht sich eine SMS-Nummer in der Regel auf eine Person, aber die Nummer kann an eine andere Person übertragen werden. Umgekehrt bezieht sich ein Facebook-Konto in der Regel auf eine Person perPetuität, obwohl es nicht ungewöhnlich ist, dass zwei Personen ein Facebook-Konto teilen.

In den meisten Kanälen sollten Sie sich ein Kanalkonto als eine Art Postfach vorstellen, in dem Nachrichten zugestellt werden können. Es ist typisch für die meisten Kanäle, mehrere Adressen einem einzelnen Postfach zuzuordnen. Beispielsweise kann "jdoe@contoso.com" und "john.doe@service.contoso.com" in denselben Posteingang aufgelöst werden. Einige Kanäle gehen einen Schritt weiter und ändern die Adresse des Kontos basierend auf dem Bot, auf den sie zugreift. Beispielsweise ändert Facebook Benutzer-IDs, sodass jeder Bot eine andere Adresse zum Senden und Empfangen von Nachrichten hat.

In einigen Fällen ist es zwar möglich, die Äquivalenz zwischen Adressen herzustellen, die Äquivalenz zwischen Postfächern und Äquivalenz zwischen Personen erfordert zwar Kenntnisse über die Konventionen innerhalb des Kanals und ist in vielen Fällen nicht möglich.

Ein Bot wird über seine Kanalkontoadresse über das Feld recipient zu Aktivitäten informiert, die an den Bot gesendet werden.

Regeln für Kanalkonten

• Kanalkonten haben nur innerhalb ihres zugeordneten Kanals Bedeutung.
• Mehrere IDs können in dasselbe Konto aufgelöst werden.
• Ordinalvergleich kann verwendet werden, um festzustellen, dass zwei IDs identisch sind.
• Es gibt in der Regel keinen Vergleich, der verwendet werden kann, um zu ermitteln, ob zwei verschiedene IDs in dasselbe Konto, Bot oder dieselbe Person aufgelöst werden.
• Die Stabilität von Zuordnungen zwischen IDs, Konten, Postfächern und Personen hängt vom Kanal ab.

Unterhaltungs-ID

Nachrichten werden im Kontext einer Unterhaltung gesendet und empfangen, die anhand der ID identifizierbar ist.

Beispiel: "conversation": { "id": "1234" }

Eine Unterhaltung enthält einen Austausch von Nachrichten und anderen Aktivitäten. Jede Unterhaltung hat null oder mehr Aktivitäten, und jede Aktivität wird in genau einer Unterhaltung angezeigt. Unterhaltungen können unbefristet sein oder unterschiedliche Anfangs- und Enden haben. Der Prozess des Erstellens, Änderns oder Beendens einer Unterhaltung erfolgt innerhalb des Kanals – eine Unterhaltung ist nur vorhanden, während der Kanal darüber informiert ist – und die Merkmale dieser Prozesse werden vom Kanal festgelegt.

Die Aktivitäten innerhalb einer Unterhaltung werden von Benutzern und Bots gesendet. Die Definition, für die Benutzer an einer Unterhaltung teilnehmen, variiert je nach Kanal und kann theoretisch Benutzer, Benutzer, die jemals eine Nachricht erhalten haben, Benutzer, die eine Nachricht gesendet haben, enthalten.

Mehrere Kanäle , z. B. SMS und möglicherweise andere, weisen die Eigenheit auf, dass die Unterhaltungs-ID einer 1:1-Unterhaltung die Id des Remotekanalkontos ist. Dieser Quirk hat zwei Nebenwirkungen:

1. Die Unterhaltungs-ID ist subjektiv, basierend auf der Person, die sie anzeigt. Wenn Teilnehmer A und B sprechen, sieht Teilnehmer A die Unterhaltungs-ID als "B" an, und Teilnehmer B sieht die Unterhaltungs-ID als "A".
2. Wenn der Bot über mehrere Kanalkonten in diesem Kanal verfügt (z. B. wenn der Bot zwei SMS-Nummern hat), reicht die Unterhaltungs-ID nicht aus, um die Unterhaltung innerhalb des Ansichtsfelds des Bots eindeutig zu identifizieren.

Daher identifiziert eine Unterhaltungs-ID nicht unbedingt eine einzelne Unterhaltung innerhalb eines Kanals selbst für einen einzelnen Bot.

Regeln für Unterhaltungs-IDs

• Unterhaltungen haben nur innerhalb ihres zugeordneten Kanals Bedeutung.
• Mehrere IDs können in dieselbe Unterhaltung aufgelöst werden.
• Die Ordinalgleichheit stellt nicht unbedingt fest, dass zwei Unterhaltungs-IDs dieselbe Unterhaltung sind, obwohl in den meisten Fällen dies der Fall ist.

Aktivitäts-ID

Aktivitäten werden innerhalb des Bot Framework-Protokolls gesendet und empfangen, und diese sind manchmal identifizierbar.

Beispiel: "id": "5678"

Aktivitäts-IDs sind optional und werden von Kanälen verwendet, um dem Bot eine Möglichkeit zu geben, in nachfolgenden API-Aufrufen auf die ID zu verweisen, sofern diese verfügbar sind:

• Antworten auf eine bestimmte Aktivität
• Abfragen der Teilnehmerliste auf Aktivitätsebene

Da keine weiteren Anwendungsfälle festgelegt wurden, gibt es keine zusätzlichen Regeln für die Behandlung von Aktivitäts-IDs.