Udostępnij za pośrednictwem

Dokumentacja interfejsu API — interfejs API direct line 3.0

  • Artykuł

Aplikację kliencą można włączyć do komunikowania się z botem przy użyciu interfejsu API direct line 3.0. Interfejs API direct line 3.0 używa standardowego standardu branżowego REST i JSON za pośrednictwem protokołu HTTPS.

Podstawowy identyfikator URI

Aby uzyskać dostęp do interfejsu API direct line 3.0, użyj jednego z tych podstawowych identyfikatorów URI dla wszystkich żądań interfejsu API:

  • W przypadku botów globalnych użyj polecenia https://directline.botframework.com

  • W przypadku bota regionalnego wprowadź następujący identyfikator URI zgodnie z wybranym regionem:

    Region (Region) Podstawowy identyfikator URI
    Europa https://europe.directline.botframework.com
    Indie https://india.directline.botframework.com

Napiwek

Żądanie może zakończyć się niepowodzeniem, jeśli używasz globalnego identyfikatora URI podstawowego dla regionalnego bota, ponieważ niektóre żądania mogą wykraczać poza granice geograficzne.

Nagłówki

Oprócz standardowych nagłówków żądań HTTP żądanie interfejsu API direct line musi zawierać Authorization nagłówek określający wpis tajny lub token do uwierzytelniania klienta, który wysyła żądanie. Authorization Określ nagłówek przy użyciu tego formatu:

Authorization: Bearer SECRET_OR_TOKEN

Aby uzyskać szczegółowe informacje na temat uzyskiwania wpisu tajnego lub tokenu, którego klient może użyć do uwierzytelniania żądań interfejsu API direct line, zobacz Uwierzytelnianie.

Kody stanu HTTP

Kod stanu HTTP zwracany z każdą odpowiedzią wskazuje wynik odpowiedniego żądania.

Kod stanu HTTP Znaczenie
200 Żądanie zakończyło się pomyślnie.
201 Żądanie zakończyło się pomyślnie.
202 Żądanie zostało zaakceptowane do przetworzenia.
204 Żądanie zakończyło się pomyślnie, ale nie została zwrócona żadna zawartość.
400 Żądanie zostało źle sformułowane lub w inny sposób niepoprawne.
401 Klient nie ma autoryzacji do tworzenia żądania. Często ten kod stanu występuje, ponieważ brakuje nagłówka Authorization lub jest on źle sformułowany.
403 Klient nie może wykonać żądanej operacji. Operacja może zakończyć się niepowodzeniem z następujących powodów.
  • Nieprawidłowy token: gdy żądanie używa tokenu, który był wcześniej prawidłowy, ale wygasł, code właściwość Error zwrócona w obiekcie ErrorResponse jest ustawiona na TokenExpiredwartość .
  • Naruszenie granicy danych: jeśli bot jest botem regionalnym, ale podstawowy identyfikator URI nie jest regionalny, niektóre żądania mogą wykraczać poza granice geograficzne.
  • Nieprawidłowy zasób docelowy: docelowy bot lub witryna jest nieprawidłowy lub został usunięty.
404 Żądany zasób nie został znaleziony. Zazwyczaj ten kod stanu wskazuje nieprawidłowy identyfikator URI żądania.
500 Wystąpił wewnętrzny błąd serwera w usłudze Direct Line.
502 Bot jest niedostępny lub zwrócił błąd. Jest to typowy kod błędu.

Uwaga

Kod stanu HTTP 101 jest używany w ścieżce połączenia protokołu WebSocket, chociaż jest to prawdopodobnie obsługiwane przez klienta protokołu WebSocket.

Błędy

Każda odpowiedź określająca kod stanu HTTP w zakresie 4xx lub 5xx będzie zawierać obiekt ErrorResponse w treści odpowiedzi zawierającej informacje o błędzie. Jeśli w zakresie 4xx pojawi się odpowiedź o błędzie, sprawdź obiekt ErrorResponse , aby zidentyfikować przyczynę błędu i rozwiązać problem przed ponownym przesłaniem żądania.

Uwaga

Kody stanu HTTP i wartości określone we code właściwości wewnątrz obiektu ErrorResponse są stabilne. Wartości określone we message właściwości wewnątrz obiektu ErrorResponse mogą ulec zmianie w czasie.

Poniższe fragmenty kodu pokazują przykładowe żądanie i wynikową odpowiedź o błędzie.

Zażądaj

POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
[detail omitted]

Response

HTTP/1.1 502 Bad Gateway
[other headers]

{
    "error": {
        "code": "BotRejectedActivity",
        "message": "Failed to send activity: bot returned an error"
    }
}

Operacje tokenu

Użyj tych operacji, aby utworzyć lub odświeżyć token, którego klient może użyć do uzyskania dostępu do jednej konwersacji.

Działanie opis
Generowanie tokenu Wygeneruj token dla nowej konwersacji.
Odśwież token Odśwież token.

Generowanie tokenu

Generuje token, który jest prawidłowy dla jednej konwersacji.

POST /v3/directline/tokens/generate
Zawartość opis
Treść żądania Obiekt TokenParameters
Zwroty Obiekt konwersacji

Odśwież token

Odświeża token.

POST /v3/directline/tokens/refresh
Zawartość opis
Treść żądania nie dotyczy
Zwroty Obiekt konwersacji

Operacje konwersacji

Użyj tych operacji, aby otworzyć rozmowę z botem i wymienić działania między klientem a botem.

Działanie opis
Rozpocznij konwersację Otwiera nową konwersację z botem.
Uzyskiwanie informacji o konwersacji Pobiera informacje o istniejącej konwersacji. Ta operacja generuje nowy adres URL strumienia protokołu WebSocket, którego klient może użyć do ponownego nawiązania połączenia z konwersacją.
Pobieranie działań Pobiera działania z bota.
Wysyłanie działania Wysyła działanie do bota.
Przekazywanie i wysyłanie plików Przekazuje i wysyła pliki jako załączniki.

Rozpocznij konwersację

Otwiera nową konwersację z botem.

POST /v3/directline/conversations
Zawartość opis
Treść żądania Obiekt TokenParameters
Zwroty Obiekt konwersacji

Uzyskiwanie informacji o konwersacji

Pobiera informacje o istniejącej konwersacji, a także generuje nowy adres URL strumienia protokołu WebSocket, którego klient może użyć do ponownego nawiązania połączenia z konwersacją. Opcjonalnie możesz podać watermark parametr w identyfikatorze URI żądania, aby wskazać najnowszy komunikat widoczny przez klienta.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}
Zawartość opis
Treść żądania nie dotyczy
Zwroty Obiekt konwersacji

Pobieranie działań

Pobiera działania z bota dla określonej konwersacji. Opcjonalnie możesz podać watermark parametr w identyfikatorze URI żądania, aby wskazać najnowszy komunikat widoczny przez klienta.

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}
Zawartość opis
Treść żądania nie dotyczy
Zwroty Obiekt ActivitySet. Odpowiedź zawiera watermark jako właściwość ActivitySet obiektu. Klienci powinni stronicować dostępne działania, rozwijając watermark wartość, dopóki nie zostaną zwrócone żadne działania.

Wysyłanie działania

Wysyła działanie do bota.

POST /v3/directline/conversations/{conversationId}/activities
Zawartość opis
Treść żądania Obiekt Działania
Zwroty ZasóbResponse zawierający właściwość określającą id identyfikator działania, który został wysłany do bota.

Przekazywanie i wysyłanie plików

Przekazuje i wysyła pliki jako załączniki. userId Ustaw parametr w identyfikatorze URI żądania, aby określić identyfikator użytkownika wysyłającego załączniki.

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}
Zawartość opis
Treść żądania W przypadku pojedynczego załącznika wypełnij treść żądania zawartością pliku. W przypadku wielu załączników utwórz treść żądania wieloczęściowego zawierającą jedną część dla każdego załącznika, a także (opcjonalnie) jedną część obiektu Działania , która powinna służyć jako kontener dla określonych załączników. Aby uzyskać więcej informacji, zobacz Wysyłanie działania do bota.
Zwroty ZasóbResponse zawierający właściwość określającą id identyfikator działania, który został wysłany do bota.

Uwaga

Przekazane pliki są usuwane po 24 godzinach.

Schemat

Schemat Direct Line 3.0 zawiera wszystkie obiekty zdefiniowane przez schemat platformy Bot Framework, a także niektóre obiekty specyficzne dla linii bezpośredniej.

ActivitySet, obiekt

Definiuje zestaw działań.

Właściwość Type Opis
Działania Działanie[] Tablica obiektów Działania .
Znak wodny string Maksymalny limit aktywności w zestawie. Klient może użyć watermark wartości , aby wskazać najnowszy komunikat widoczny podczas pobierania działań z bota lub podczas generowania nowego adresu URL strumienia protokołu WebSocket.

Obiekt konwersacji

Definiuje konwersację bezpośrednią.

Właściwość Type Opis
identyfikator konwersacji string Identyfikator, który jednoznacznie identyfikuje konwersację, dla której określony token jest prawidłowy.
Etag string Element HTTP ETag (tag jednostki).
expires_in Liczba Liczba sekund do wygaśnięcia tokenu.
referenceGrammarId string Identyfikator gramatyki referencyjnej dla tego bota.
streamUrl string Adres URL strumienia wiadomości konwersacji.
Tokenu string Token prawidłowy dla określonej konwersacji.

TokenParameters, obiekt

Parametry tworzenia tokenu.

Właściwość Type Opis
Etag string Element HTTP ETag (tag jednostki).
trustedOrigins string[] Zaufane źródła do osadzania w tokenie.
użytkownik Konto kanału Konto użytkownika do osadzenia w tokenie.

Działania

Dla każdego działania odbieranego przez klienta z bota za pośrednictwem linii bezpośredniej:

  • Karty załączników są zachowywane.
  • Adresy URL przekazanych załączników są ukryte za pomocą łącza prywatnego.
  • Właściwość channelData jest zachowywana bez modyfikacji.

Klienci mogą odbierać wiele działań z bota w ramach elementu ActivitySet.

Gdy klient wysyła wiadomość Activity do bota za pośrednictwem linii bezpośredniej:

  • Właściwość type określa typ działania, które wysyła (zazwyczaj komunikat).
  • Właściwość from musi zostać wypełniona identyfikatorem użytkownika wybranym przez klienta.
  • Załączniki mogą zawierać adresy URL istniejących zasobów lub adresów URL przekazanych za pośrednictwem punktu końcowego załącznika direct line.
  • Właściwość channelData jest zachowywana bez modyfikacji.
  • Całkowity rozmiar działania, w przypadku serializacji do formatu JSON i zaszyfrowania, nie może przekraczać 256 tys. znaków. Zalecamy zachowanie działań poniżej 150 0000. Jeśli potrzebujesz więcej danych, rozważ podzielenie działania lub użycie załączników.

Klienci mogą wysyłać pojedyncze działanie na żądanie.

Dodatkowe zasoby