Wysyłanie działania do bota w interfejsie API 3.0 Direct Line
Korzystając z protokołu Direct Line 3.0, klienci i boty mogą wymieniać różne typy działań, w tym działania komunikatów, wpisywanie działań i działania niestandardowe obsługiwane przez bota. Klient może wysłać jedno działanie na żądanie.
Wysyłanie działania
Aby wysłać działanie do bota, klient musi utworzyć obiekt Activity w celu zdefiniowania działania, a następnie wysłać POST żądanie do https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities, określając obiekt Activity w treści żądania.
Poniższe fragmenty kodu zawierają przykład żądania działania wysyłania i odpowiedzi.
Żądanie
POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: application/json
[other headers]
{
"locale": "en-EN",
"type": "message",
"from": {
"id": "user1"
},
"text": "hello"
}
Reakcja
Po dostarczeniu działania do bota usługa odpowiada kodem stanu HTTP, który odzwierciedla kod stanu bota. Jeśli bot generuje błąd, odpowiedź HTTP 502 ("Zła brama") jest zwracana do klienta w odpowiedzi na żądanie działania wysyłania.
Uwaga
Może to być spowodowane faktem, że nie użyto poprawnego tokenu. Do wysyłania działania można użyć tylko tokenu otrzymanego przed rozpoczęciem konwersacji .
Jeśli post zakończy się pomyślnie, odpowiedź zawiera ładunek JSON określający identyfikator działania, który został wysłany do bota.
HTTP/1.1 200 OK
[other headers]
{
"id": "0001"
}
Łączny czas wysyłania żądania/odpowiedzi działania
Łączny czas publikowania wiadomości w konwersacji Direct Line jest sumą następujących elementów:
- Czas tranzytowy żądania HTTP do podróży od klienta do usługi Direct Line
- Wewnętrzny czas przetwarzania w Direct Line (zazwyczaj krótszy niż 120 ms)
- Czas przesyłania z usługi Direct Line do bota
- Czas przetwarzania w ramach bota
- Czas przesyłania odpowiedzi HTTP na powrót do klienta
Wysyłanie załączników do bota
W niektórych sytuacjach klient może potrzebować wysyłania załączników do bota, takiego jak obrazy lub dokumenty. Klient może wysyłać załączniki do bota, określając adresy URL załączników w obiekcie Działania, którego wysyła, lub przekazując załączniki przy użyciu POST /v3/directline/conversations/{conversationId}/activities metody POST /v3/directline/conversations/{conversationId}/upload.
Wysyłanie załączników według adresu URL
Aby wysłać jeden lub więcej załączników w ramach obiektu Działania przy użyciu polecenia POST /v3/directline/conversations/{conversationId}/activities, po prostu uwzględnij jeden lub więcej obiektów załącznika w obiekcie Działania i ustaw contentUrl właściwość każdego obiektu Załącznika, aby określić http, HTTPS lub data identyfikator URI załącznika.
Wysyłanie załączników przez przekazanie
Często klient może mieć obrazy lub dokumenty na urządzeniu, które chce wysłać do bota, ale nie ma adresów URL odpowiadających tym plikom. W takiej sytuacji klient może wysłać POST /v3/directline/conversations/{conversationId}/upload żądanie wysłania załączników do bota przez przekazanie. Format i zawartość żądania zależą od tego, czy klient wysyła pojedynczy załącznik , czy wysyła wiele załączników.
Wysyłanie pojedynczego załącznika przez przekazanie
Aby wysłać pojedynczy załącznik przez przekazanie, wyślij to żądanie:
POST https://directline.botframework.com/v3/directline/conversations/{conversationId}/upload?userId={userId}
Authorization: Bearer SECRET_OR_TOKEN
Content-Type: TYPE_OF_ATTACHMENT
Content-Disposition: ATTACHMENT_INFO
[other headers]
[file content]
W tym identyfikatorze URI żądania zastąp ciąg {conversationId} identyfikatorem konwersacji i {userId} identyfikatorem użytkownika wysyłającego wiadomość. Parametr userId jest wymagany. W nagłówkach żądania ustaw wartość Content-Type , aby określić typ załącznika i ustawić, Content-Disposition aby określić nazwę pliku załącznika.
Poniższe fragmenty kodu zawierają przykład żądania i odpowiedzi na żądanie załącznika Wysyłania (pojedynczego).
Żądanie
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: image/jpeg
Content-Disposition: name="file"; filename="badjokeeel.jpg"
[other headers]
[JPEG content]
Reakcja
Jeśli żądanie zakończy się pomyślnie, działanie komunikatu zostanie wysłane do bota po zakończeniu przekazywania, a odpowiedź odebrana przez klienta będzie zawierać identyfikator wysłanego działania.
HTTP/1.1 200 OK
[other headers]
{
"id": "0003"
}
Wysyłanie wielu załączników przez przekazanie
Aby wysłać wiele załączników przez przekazanie, POST żądanie wieloczęściowe do punktu końcowego /v3/directline/conversations/{conversationId}/upload .
Content-Type Ustaw nagłówek żądania multipart/form-data na i dołącz Content-Type nagłówek i nagłówek dla każdej części, aby określić typ i Content-Disposition nazwę pliku każdego załącznika. W identyfikatorze URI żądania ustaw userId parametr na identyfikator użytkownika, który wysyła komunikat.
Obiekt w żądaniu można uwzględnićActivity, dodając część określającą wartość application/vnd.microsoft.activitynagłówka Content-Type . Jeśli żądanie zawiera działanie, załączniki określone przez inne części ładunku są dodawane jako załączniki do tego działania przed wysłaniem. Jeśli żądanie nie zawiera działania, zostanie utworzone puste działanie, które będzie służyć jako kontener, w którym są wysyłane określone załączniki.
Poniższe fragmenty kodu zawierają przykład żądania i odpowiedzi wyślij (wiele) załączników. W tym przykładzie żądanie wysyła komunikat zawierający jakiś tekst i pojedynczy załącznik obrazu. Dodatkowe części można dodać do żądania, aby uwzględnić wiele załączników w tej wiadomości.
Żądanie
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: multipart/form-data; boundary=----DD4E5147-E865-4652-B662-F223701A8A89
[other headers]
----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: image/jpeg
Content-Disposition: form-data; name="file"; filename="badjokeeel.jpg"
[other headers]
[JPEG content]
----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: application/vnd.microsoft.activity
[other headers]
{
"type": "message",
"from": {
"id": "user1"
},
"text": "Hey I just IM'd you\n\nand this is crazy\n\nbut here's my webhook\n\nso POST me maybe"
}
----DD4E5147-E865-4652-B662-F223701A8A89
Reakcja
Jeśli żądanie zakończy się pomyślnie, działanie komunikatu zostanie wysłane do bota po zakończeniu przekazywania, a odpowiedź odebrana przez klienta będzie zawierać identyfikator wysłanego działania.
HTTP/1.1 200 OK
[other headers]
{
"id": "0004"
}