Dokumentacja interfejsu API — interfejs API Direct Line 3.0

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

Podstawowy adres 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	Podstawowy adres URI
  Europa	https://europe.directline.botframework.com
  India	https://india.directline.botframework.com

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 wystawiającego żą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.

Errors

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.

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

Żądanie

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

Odpowiedź

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.

Generowanie tokena

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

POST /v3/directline/tokens/generate

Odśwież token

Odświeża token.

POST /v3/directline/tokens/refresh

Operacje konwersacji

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

Rozpocznij rozmowę

Otwiera nową konwersację z botem.

POST /v3/directline/conversations

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}

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}

Wysyłanie działania

Wysyła działanie do bota.

POST /v3/directline/conversations/{conversationId}/activities

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}

Schema

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

ActivitySet, obiekt

Definiuje zestaw działań.

Obiekt konwersacji

Definiuje konwersację Direct Line.

TokenParameters, obiekt

Parametry tworzenia tokenu.

Activities

Dla każdego działania odbieranego przez klienta z bota za pośrednictwem Direct Line:

• 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 Direct Line:

• 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

• Specyfikacja protokołu aktywności