Udostępnij za pośrednictwem

Dokumentacja interfejsu API — interfejs API Direct Line 1.1

  • Artykuł

Ważne

Ten artykuł zawiera informacje referencyjne dotyczące interfejsu API Direct Line w wersji 1.1. Jeśli tworzysz nowe połączenie między aplikacją kliencką i botem, zamiast tego użyj interfejsu API Direct Line 3.0.

Możesz umożliwić aplikacji klienckiej komunikowanie się z botem przy użyciu interfejsu API Direct Line 1.1. Direct Line interfejs API 1.1 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 1.1, użyj tego podstawowego identyfikatora URI dla wszystkich żądań interfejsu API:

https://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 w celu uwierzytelnienia klienta, który wysyła żądanie. Nagłówek można określić Authorization przy użyciu schematu "Bearer" lub schematu "BotConnector".

Schemat elementu nośnego:

Authorization: Bearer SECRET_OR_TOKEN

Schemat BotConnector:

Authorization: BotConnector 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.
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 wykonania żą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. Często ten kod stanu występuje, ponieważ Authorization nagłówek określa nieprawidłowy token lub wpis tajny.
404 Nie można odnaleźć żądanego zasobu. Zazwyczaj ten kod stanu wskazuje nieprawidłowy identyfikator URI żądania.
500 Wystąpił wewnętrzny błąd serwera w usłudze Direct Line
502 Wystąpił błąd w bocie; bot jest niedostępny lub zwraca błąd. Jest to typowy kod błędu.

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.

Operacja Opis
Generowanie tokenu Wygeneruj token dla nowej konwersacji.
Odśwież token Odśwież token.

Generowanie tokenu

Generuje token, który jest ważny dla jednej konwersacji.

POST /api/tokens/conversation
Zawartość Opis
Treść żądania n/d
Zwraca Ciąg reprezentujący token

Odśwież token

Odświeża token.

GET /api/tokens/{conversationId}/renew
Zawartość Opis
Treść żądania n/d
Zwraca Ciąg reprezentujący nowy token

Operacje konwersacji

Użyj tych operacji, aby otworzyć rozmowę z botem i wymieniać komunikaty między klientem a botem.

Operacja Opis
Rozpocznij konwersację Otwiera nową konwersację z botem.
Pobieranie komunikatów Pobiera komunikaty z bota.
Wysyłanie wiadomości Wysyła wiadomość do bota.
Przekazywanie i wysyłanie plików Przekazuje i wysyła pliki jako załączniki.

Rozpocznij konwersację

Otwiera nową konwersację z botem.

POST /api/conversations
Zawartość Opis
Treść żądania n/d
Zwraca Obiekt konwersacji

Pobieranie komunikatów

Pobiera komunikaty z bota dla określonej konwersacji. watermark Ustaw parametr w identyfikatorze URI żądania, aby wskazać najnowszy komunikat widoczny przez klienta.

GET /api/conversations/{conversationId}/messages?watermark={watermark_value}
Zawartość Opis
Treść żądania n/d
Zwraca Obiekt MessageSet . Odpowiedź zawiera watermark się jako właściwość MessageSet obiektu. Klienci powinni stronicować dostępne komunikaty, rozwijając watermark wartość, dopóki nie zostaną zwrócone żadne komunikaty.

Wysyłanie wiadomości

Wysyła wiadomość do bota.

POST /api/conversations/{conversationId}/messages
Zawartość Opis
Treść żądania Obiekt Message
Zwraca Żadne dane nie są zwracane w treści odpowiedzi. Usługa odpowiada za pomocą kodu stanu HTTP 204, jeśli komunikat został wysłany pomyślnie. Klient może uzyskać wysłany komunikat (wraz z komunikatami wysłanymi przez bota do klienta) przy użyciu operacji Pobierz komunikaty .

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 /api/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, która zawiera jedną część dla każdego załącznika, a także (opcjonalnie) jedną część dla obiektu Message , który powinien służyć jako kontener dla określonych załączników. Aby uzyskać więcej informacji, zobacz Wysyłanie komunikatu do bota.
Zwraca Żadne dane nie są zwracane w treści odpowiedzi. Usługa odpowiada za pomocą kodu stanu HTTP 204, jeśli komunikat został wysłany pomyślnie. Klient może uzyskać wysłany komunikat (wraz z komunikatami wysłanymi przez bota do klienta) przy użyciu operacji Pobierz komunikaty .

Uwaga

Przekazane pliki są usuwane po 24 godzinach.

Schemat

Direct Line schemat 1.1 jest uproszczoną kopią schematu platformy Bot Framework w wersji 1, która zawiera następujące obiekty.

Obiekt komunikatu

Definiuje komunikat wysyłany przez klienta do bota lub odbierany z bota.

Właściwość Typ Opis
id ciąg Identyfikator, który jednoznacznie identyfikuje komunikat (przypisany przez Direct Line).
identyfikator konwersacji ciąg Identyfikator identyfikujący konwersację.
Utworzone ciąg Data i godzina utworzenia komunikatu w formacie ISO-8601.
Z ciąg Identyfikator identyfikujący użytkownika, który jest nadawcą wiadomości. Podczas tworzenia komunikatu klienci powinni ustawić tę właściwość na stabilny identyfikator użytkownika. Mimo że Direct Line przypisze identyfikator użytkownika, jeśli nie zostanie podany żaden, zazwyczaj powoduje to nieoczekiwane zachowanie.
Tekst ciąg Tekst wiadomości wysyłanej od użytkownika do bota lub bota do użytkownika.
channelData object Obiekt zawierający zawartość specyficzną dla kanału. Niektóre kanały udostępniają funkcje, które wymagają dodatkowych informacji, których nie można przedstawić przy użyciu schematu załącznika. W takich przypadkach ustaw tę właściwość na zawartość specyficzną dla kanału zgodnie z definicją w dokumentacji kanału. Te dane są wysyłane niezmodyfikowane między klientem a botem. Ta właściwość musi być ustawiona na obiekt złożony lub pozostawiona pusta. Nie ustawiaj go na ciąg, liczbę lub inny prosty typ.
Obrazów ciąg[] Tablica ciągów zawierających adresy URL obrazów, które zawiera komunikat. W niektórych przypadkach ciągi w tej tablicy mogą być względnymi adresami URL. Jeśli jakikolwiek ciąg w tej tablicy nie rozpoczyna się od ciągu "http" lub "https", przed utworzeniem pełnego adresu URL.https://directline.botframework.com
Załączniki Załącznik[] Tablica obiektów załączników , które reprezentują załączniki niezwiązane z obrazem, które zawiera komunikat. Każdy obiekt w tablicy zawiera url właściwość i contentType właściwość. W komunikatach odbieranych przez klienta z bota url właściwość może czasami określać względny adres URL. W przypadku każdej url wartości właściwości, która nie zaczyna się od ciągu "http" lub "https", należy https://directline.botframework.com wstępnie utworzyć pełny adres URL.

W poniższym przykładzie pokazano obiekt Message zawierający wszystkie możliwe właściwości. W większości przypadków podczas tworzenia komunikatu klient musi podać from tylko właściwość i co najmniej jedną właściwość zawartości (na przykład text, images, attachmentslub channelData).

{
    "id": "CuvLPID4kDb|000000000000000004",
    "conversationId": "CuvLPID4kDb",
    "created": "2016-10-28T21:19:51.0357965Z",
    "from": "examplebot",
    "text": "Hello!",
    "channelData": {
        "examplefield": "abc123"
    },
    "images": [
        "/attachments/CuvLPID4kDb/0.jpg?..."
    ],
    "attachments": [
        {
            "url": "https://example.com/example.docx",
            "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
        }, 
        {
            "url": "https://example.com/example.doc",
            "contentType": "application/msword"
        }
    ]
}

MessageSet, obiekt

Definiuje zestaw komunikatów.

Właściwość Typ Opis
Wiadomości Komunikat[] Tablica obiektów Message .
Znak wodny ciąg Maksymalny limit komunikatów w zestawie. Klient może użyć watermark wartości , aby wskazać najnowszy komunikat, który widział podczas pobierania komunikatów z bota.

Obiekt załącznika

Definiuje załącznik niezwiązany z obrazem.

Właściwość Typ Opis
Contenttype ciąg Typ nośnika zawartości w załączniku.
Adres url ciąg Adres URL zawartości załącznika.

Obiekt konwersacji

Definiuje Direct Line konwersację.

Właściwość Typ Opis
identyfikator konwersacji ciąg Identyfikator, który jednoznacznie identyfikuje konwersację, dla której określony token jest prawidłowy.
Tokenu ciąg Token, który jest prawidłowy dla określonej konwersacji.
expires_in liczba Liczba sekund do wygaśnięcia tokenu.

Obiekt błędu

Definiuje błąd.

Właściwość Typ Opis
Kod ciąg Kod błędu. Jedną z następujących wartości: MissingProperty, MalformedData, NotFound, ServiceError, Internal, InvalidRange, NotSupported, NotAllowed, BadCertificate.
message ciąg Opis błędu.
statusCode liczba Kod stanu.

ErrorMessage, obiekt

Ustandaryzowany ładunek komunikatu.

Właściwość Typ Opis
Błąd Błąd Obiekt Error zawierający informacje o błędzie.