Odeslání aktivity robotovi v rozhraní API Direct Line 3.0
Pomocí protokolu Direct Line 3.0 si klienti a roboti můžou vyměňovat několik různých typů aktivit, včetně aktivit zpráv, psaní a vlastních aktivit, které robot podporuje. Klient může odeslat jednu aktivitu na každou žádost.
Odeslání aktivity
Chcete-li odeslat aktivitu robotovi, musí klient vytvořit objekt aktivity , který definuje aktivitu, a pak vydat POST požadavek na https://directline.botframework.com/v3/directline/conversations/{conversationId}/activitiesobjekt , který určuje objekt Activity v textu požadavku.
Následující fragmenty kódu poskytují příklad požadavku a odpovědi Nasměrovat aktivitu.
Žádost
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"
}
Odpověď
Když se aktivita doručí robotovi, služba odpoví stavovým kódem HTTP, který odráží stavový kód robota. Pokud robot vygeneruje chybu, vrátí se klientovi odpověď HTTP 502 ("Chybná brána") v reakci na požadavek odeslat aktivitu.
Poznámka
Příčinou může být skutečnost, že se nepoužil správný token. K odeslání aktivity je možné použít pouze token, který byl přijat pro zahájení konverzace .
Pokud je post úspěšný, odpověď obsahuje datovou část JSON, která určuje ID aktivity odeslané robotovi.
HTTP/1.1 200 OK
[other headers]
{
"id": "0001"
}
Celková doba pro požadavek/odpověď na odeslání aktivity
Celková doba odeslání zprávy do Direct Line konverzace je součet následujících hodnot:
- Doba přenosu požadavku HTTP z klienta do služby Direct Line
- Doba interního zpracování do Direct Line (obvykle méně než 120ms)
- Doba přenosu ze služby Direct Line do robota
- Doba zpracování v rámci robota
- Doba přenosu odpovědi HTTP, která se má vrátit do klienta
Odeslání příloh robotovi
V některých situacích může klient posílat robotovi přílohy, jako jsou obrázky nebo dokumenty. Klient může robotovi odesílat přílohy buď tak, že zadá adresy URL příloh v objektu Activity , který odesílá, POST /v3/directline/conversations/{conversationId}/activities nebo nahraje přílohy pomocí POST /v3/directline/conversations/{conversationId}/upload.
Odeslání příloh podle adresy URL
Chcete-li odeslat jednu nebo více příloh jako součást objektu Aktivity pomocí POST /v3/directline/conversations/{conversationId}/activities, jednoduše vložte jeden nebo více objektů Attachment do objektu Activity a nastavte contentUrl vlastnost každého objektu Attachment tak, aby určila HTTP, HTTPS nebo data URI přílohy.
Odeslání příloh při nahrání
Klient může často mít na zařízení, které chce robotovi odeslat, image nebo dokumenty, ale žádné adresy URL odpovídající těmto souborům. V takovém případě může klient odeslat žádost o POST /v3/directline/conversations/{conversationId}/upload odeslání příloh robotovi nahráním. Formát a obsah požadavku bude záviset na tom, jestli klient odesílá jednu přílohu nebo více příloh.
Odeslání jedné přílohy nahráním
Pokud chcete odeslat jednu přílohu nahráním, vydejte tento požadavek:
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]
V tomto identifikátoru URI požadavku nahraďte {conversationId} ID konverzace a {userId} ID uživatele, který zprávu odesílá. Parametr userId je povinný. V hlavičce požadavku nastavte Content-Type na typ přílohy a nastavte Content-Disposition na určení názvu souboru přílohy.
Následující fragmenty kódu poskytují příklad požadavku a odpovědi Odeslat (jednu) přílohu.
Žádost
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]
Odpověď
Pokud je požadavek úspěšný, po dokončení nahrávání se robotovi odešle zpráva Aktivita a odpověď, kterou klient obdrží, bude obsahovat ID aktivity, která byla odeslána.
HTTP/1.1 200 OK
[other headers]
{
"id": "0003"
}
Odeslání více příloh nahráním
Pokud chcete odeslat více příloh po nahrání, POST požadavek s více částmi do koncového /v3/directline/conversations/{conversationId}/upload bodu.
Content-Type Pokud chcete určit typ a název každé přílohy, nastavte hlavičku požadavku na multipart/form-data a zahrňte Content-Type do nich hlavičku a Content-Disposition hlavičku pro každou část. V identifikátoru URI požadavku nastavte userId parametr na ID uživatele, který zprávu odesílá.
Do požadavku můžete zahrnout Activity objekt přidáním části, která určuje hodnotu application/vnd.microsoft.activityhlavičky Content-Type . Pokud požadavek obsahuje aktivitu, přílohy určené jinými částmi datové části se před odesláním přidají jako přílohy k dané aktivitě. Pokud požadavek neobsahuje aktivitu, vytvoří se prázdná aktivita, která bude sloužit jako kontejner, ve kterém se odesílají zadané přílohy.
Následující fragmenty kódu poskytují příklad požadavku a odpovědi Odeslat (více) příloh. V tomto příkladu požadavek odešle zprávu, která obsahuje text a přílohu s jedním obrázkem. Do požadavku je možné přidat další části, aby se do této zprávy zahrnulo více příloh.
Žádost
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
Odpověď
Pokud je požadavek úspěšný, po dokončení nahrávání se robotovi odešle zpráva Aktivita a odpověď, kterou klient obdrží, bude obsahovat ID aktivity, která byla odeslána.
HTTP/1.1 200 OK
[other headers]
{
"id": "0004"
}