ID fields in the Bot Framework (Pola identyfikatorów w usłudze Bot Framework)

DOTYCZY: ZESTAW SDK w wersji 4

W tym przewodniku opisano charakterystykę pól identyfikatorów w strukturze Bot Framework.

Identyfikator kanału

Każdy kanał platformy Bot Framework jest identyfikowany przez unikatowy identyfikator.

Przykład: "channelId": "slack"

Identyfikatory kanałów służą jako przestrzenie nazw dla innych identyfikatorów. Wywołania środowiska uruchomieniowego w protokole Bot Framework muszą odbywać się w kontekście kanału; kanał ma znaczenie dla konwersacji i identyfikatorów kont używanych podczas komunikacji.

Zgodnie z konwencją wszystkie identyfikatory kanałów są małymi literami. Kanały gwarantują, że identyfikatory kanałów, które emitują, mają spójną wielkość liter, a tym samym boty mogą używać porównań porządkowych w celu ustalenia równoważności.

Reguły dotyczące identyfikatorów kanałów

• W identyfikatorach kanałów jest rozróżniana wielkość liter.

Uchwyt bota

Każdy bot zarejestrowany w usłudze Azure AI Bot Service ma dojście bota.

Przykład: FooBot

Dojście bota reprezentuje rejestrację bota w usłudze Azure AI Bot Service w trybie online. Ta rejestracja jest skojarzona z punktem końcowym elementu webhook HTTP i rejestracjami z kanałami.

Usługa Azure AI Bot Service zapewnia unikatowość dojść bota. Witryna Azure Portal przeprowadza sprawdzanie unikatowości bez uwzględniania wielkości liter (co oznacza, że odmiany wielkości liter dojścia bota są traktowane jako pojedynczy uchwyt), chociaż jest to cecha witryny Azure Portal, a niekoniecznie sama obsługa bota.

Reguły obsługi botów

• Dojścia botów są unikatowe (bez uwzględniania wielkości liter) w strukturze Bot Framework.

Identyfikator aplikacji

Każdy bot zarejestrowany w usłudze Azure AI Bot Service ma identyfikator aplikacji.

Uwaga

Wcześniej aplikacje były często określane jako "Aplikacje MSA" lub "APLIKACJE MSA/AAD". Aplikacje są teraz częściej określane po prostu jako "aplikacje", ale niektóre elementy protokołu mogą odnosić się do aplikacji jako "APLIKACJE MSA" w utrwalaniu.

Przykład: "msaAppId": "353826a6-4557-45f8-8d88-6aa0526b8f77"

Aplikacja reprezentuje rejestrację w portalu aplikacji zespołu tożsamości i służy jako mechanizm tożsamości typu service-to-service w ramach protokołu środowiska uruchomieniowego Bot Framework. Aplikacje mogą mieć inne skojarzenia niezwiązane z botem, takie jak witryny internetowe i aplikacje mobilne/klasyczne.

Każdy zarejestrowany bot ma dokładnie jedną aplikację. Chociaż właściciel bota nie może niezależnie zmienić aplikacji skojarzonej z botem, zespół bot framework może to zrobić w kilku wyjątkowych przypadkach.

Boty i kanały mogą używać identyfikatorów aplikacji do unikatowego identyfikowania zarejestrowanego bota.

Identyfikatory aplikacji są gwarantowane jako identyfikatory GUID. Identyfikatory aplikacji powinny być porównywane bez uwzględniania wielkości liter.

Reguły dla identyfikatorów aplikacji

• Identyfikatory aplikacji są unikatowe (porównanie identyfikatorów GUID) na platformie Microsoft App.
• Każdy bot ma dokładnie jedną odpowiednią aplikację.
• Zmiana aplikacji skojarzonej z botem wymaga pomocy zespołu Bot Framework.

Konto kanału

Każdy bot i użytkownik ma konto w każdym kanale. Konto zawiera identyfikator (id) i inne informacyjne dane niestrukturalnych bota, takie jak opcjonalna nazwa.

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

To konto opisuje adres w kanale, w którym można wysyłać i odbierać komunikaty. W niektórych przypadkach te rejestracje istnieją w ramach jednej usługi, takiej jak Facebook. W innych systemach są one rejestrowane w wielu systemach (adresy e-mail, numery telefonów). W bardziej anonimowych kanałach, takich jak czat internetowy, rejestracja może być efemeryczna.

Konta kanału są zagnieżdżone w kanałach. Na przykład konto na Facebooku jest po prostu liczbą. Ta liczba może mieć inne znaczenie w innych kanałach i nie ma znaczenia poza wszystkimi kanałami.

Relacja między kontami kanału a użytkownikami (rzeczywistymi osobami) zależy od konwencji skojarzonych z każdym kanałem. Na przykład numer SMS zazwyczaj odnosi się do jednej osoby, ale numer może zostać przeniesiony do kogoś innego. Z drugiej strony, konto na Facebooku zwykle odnosi się do jednej osoby w wytrwałości, chociaż nie jest rzadkością dla dwóch osób do udostępnienia konta na Facebooku.

W większości kanałów należy traktować konto kanału jako rodzaj skrzynki pocztowej, w której można dostarczać wiadomości. Większość kanałów jest typowa dla większości kanałów, aby umożliwić mapowania wielu adresów na pojedynczą skrzynkę pocztową. Na przykład "jdoe@contoso.com" i "john.doe@service.contoso.com" mogą być rozpoznawane w tej samej skrzynce odbiorczej. Niektóre kanały idą krok dalej i zmieniają adres konta na podstawie tego, do którego bota uzyskuje dostęp. Na przykład Facebook zmienia identyfikatory użytkowników, aby każdy bot miał inny adres do wysyłania i odbierania wiadomości.

Chociaż w niektórych przypadkach istnieje możliwość ustanowienia równoważności między adresami, ustanowienie równoważności między skrzynkami pocztowymi a równoważnością między osobami wymaga znajomości konwencji w kanale i jest w wielu przypadkach niemożliwe.

Bot jest informowany o swoim adresie konta kanału recipient za pośrednictwem pola dotyczącego działań wysyłanych do bota.

Reguły dla kont kanałów

• Konta kanału mają znaczenie tylko w ramach skojarzonego kanału.
• Więcej niż jeden identyfikator może zostać rozpoznany dla tego samego konta.
• Porównanie porządkowe może służyć do ustalenia, że dwa identyfikatory są takie same.
• Zazwyczaj nie ma porównania, którego można użyć do określenia, czy dwa różne identyfikatory rozpoznają to samo konto, bota lub osobę.
• Stabilność skojarzeń między identyfikatorami, kontami, skrzynkami pocztowymi i osobami zależy od kanału.

Identyfikator konwersacji

Wiadomości są wysyłane i odbierane w kontekście konwersacji, która jest możliwa do zidentyfikowania według identyfikatora.

Przykład: "conversation": { "id": "1234" }

Konwersacja zawiera wymianę wiadomości i innych działań. Każda konwersacja ma co najmniej zero działań, a każde działanie jest wyświetlane w dokładnie jednej konwersacji. Konwersacje mogą być bezterminowe lub mogą mieć odrębne rozpoczynanie i końce. Proces tworzenia, modyfikowania lub kończenia konwersacji występuje w kanale — konwersacja istnieje tylko wtedy, gdy kanał jest o nim świadomy — a cechy tych procesów są ustanawiane przez kanał.

Działania w konwersacji są wysyłane przez użytkowników i botów. Definicja, dla której użytkownicy "uczestniczą" w konwersacji, różni się w zależności od kanału i teoretycznie mogą obejmować obecnych użytkowników, użytkowników, którzy kiedykolwiek otrzymali wiadomość, użytkowników, którzy wysłali wiadomość.

Kilka kanałów , takich jak SMS, i ewentualnie inne — ma dziwaczne, że identyfikator konwersacji przypisany do konwersacji 1:1 jest identyfikatorem konta kanału zdalnego. To dziwactwa ma dwa skutki uboczne:

1. Identyfikator konwersacji jest subiektywny, na podstawie tego, kto go wyświetla. Jeśli uczestnicy A i B rozmawiają, uczestnik A widzi identyfikator konwersacji jako "B", a uczestnik B widzi identyfikator konwersacji jako "A".
2. Jeśli bot ma wiele kont kanałów w tym kanale (na przykład jeśli bot ma dwa numery SMS), identyfikator konwersacji nie jest wystarczający, aby jednoznacznie zidentyfikować konwersację w polu widoku bota.

W związku z tym identyfikator konwersacji nie musi jednoznacznie identyfikować jednej konwersacji w kanale nawet w przypadku pojedynczego bota.

Reguły dotyczące identyfikatorów konwersacji

• Konwersacje mają znaczenie tylko w skojarzonym kanale.
• Więcej niż jeden identyfikator może rozpoznać tę samą konwersację.
• Równość porządkowa nie musi określać, że dwa identyfikatory konwersacji są tą samą konwersacją, chociaż w większości przypadków to robi.

Identyfikator działania

Działania są wysyłane i odbierane w ramach protokołu Bot Framework, a czasami są one możliwe do zidentyfikowania.

Przykład: "id": "5678"

Identyfikatory działań są opcjonalne i stosowane przez kanały, aby dać botowi sposób odwoływania się do identyfikatora w kolejnych wywołaniach interfejsu API, jeśli są dostępne:

• Odpowiadanie na określone działanie
• Wykonywanie zapytań dotyczących listy uczestników na poziomie działania

Ponieważ nie ustalono żadnych dalszych przypadków użycia, nie ma żadnych dodatkowych zasad dotyczących traktowania identyfikatorów działań.