Sdílet prostřednictvím

Referenční informace k rozhraní API – rozhraní API Direct Line 3.0

  • Článek

Klientskou aplikaci můžete povolit komunikaci s robotem pomocí rozhraní DIRECT Line API 3.0. Rozhraní API Direct Line 3.0 používá standardní rozhraní REST a JSON přes HTTPS.

Základní identifikátor URI

Pro přístup k rozhraní API Direct Line 3.0 použijte jednu z těchto základních identifikátorů URI pro všechny požadavky rozhraní API:

  • Pro globální roboty použijte https://directline.botframework.com

  • V případě místního robota zadejte následující identifikátor URI podle vybrané oblasti:

    Oblast Základní identifikátor URI
    Evropě https://europe.directline.botframework.com
    Indie https://india.directline.botframework.com

Tip

Požadavek může selhat, pokud pro místního robota použijete globální základní identifikátor URI, protože některé požadavky můžou přesahovat geografické hranice.

Hlavičky

Kromě standardních hlaviček požadavků HTTP musí požadavek rozhraní API direct line obsahovat hlavičku Authorization , která určuje tajný klíč nebo token pro ověření klienta, který požadavek vydává. Authorization Zadejte záhlaví pomocí tohoto formátu:

Authorization: Bearer SECRET_OR_TOKEN

Podrobnosti o tom, jak získat tajný kód nebo token, který může váš klient použít k ověření požadavků rozhraní API direct line, najdete v tématu Ověřování.

Stavové kódy HTTP

Stavový kód HTTP vrácený s každou odpovědí označuje výsledek odpovídajícího požadavku.

Kód stavu HTTP Význam
200 Požadavek byl úspěšný.
201 Požadavek byl úspěšný.
202 Žádost byla přijata ke zpracování.
204 Požadavek byl úspěšný, ale nebyl vrácen žádný obsah.
400 Požadavek byl poškozený nebo jinak nesprávný.
401 Klient nemá oprávnění k provedení žádosti. K tomuto stavovém kódu často dochází, protože Authorization záhlaví chybí nebo je poškozené.
403 Klient nemůže provést požadovanou operaci. Operace může selhat z následujících důvodů.
  • Neplatný token: Pokud požadavek používá token, který byl dříve platný, ale vypršela platnost, code vlastnost Error vrácená v rámci ErrorResponse objektu je nastavena na TokenExpired.
  • Porušení hranice dat: Pokud je robot regionálním robotem, ale základní identifikátor URI není regionální, můžou některé požadavky přesahovat geografické hranice.
  • Neplatný cílový prostředek: Cílový robot nebo web je neplatný nebo byl odstraněn.
404 Požadovaný prostředek nebyl nalezen. Tento stavový kód obvykle označuje neplatný identifikátor URI požadavku.
500 Ve službě Direct Line došlo k vnitřní chybě serveru.
502 Robot není k dispozici nebo vrátil chybu. Toto je běžný kód chyby.

Poznámka:

Stavový kód HTTP 101 se používá v cestě připojení WebSocket, i když to pravděpodobně zpracovává váš klient WebSocket.

Chyby

Každá odpověď, která určuje stavový kód HTTP v rozsahu 4xx nebo 5xx, bude obsahovat objekt ErrorResponse v těle odpovědi, který poskytuje informace o chybě. Pokud se v oblasti 4xx zobrazí chybová odpověď, zkontrolujte objekt ErrorResponse a zjistěte příčinu chyby a vyřešte problém před opětovným odesláním požadavku.

Poznámka:

Stavové kódy a hodnoty HTTP zadané ve code vlastnosti uvnitř ErrorResponse objektu jsou stabilní. Hodnoty zadané v message vlastnosti Uvnitř ErrorResponse objektu se mohou v průběhu času měnit.

Následující fragmenty kódu ukazují příklad požadavku a výslednou chybovou odpověď.

Požádat

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"
    }
}

Operace s tokeny

Pomocí těchto operací můžete vytvořit nebo aktualizovat token, který může klient použít pro přístup k jedné konverzaci.

Operation Popis
Generování tokenu Vygenerujte token pro novou konverzaci.
Obnovovací token Aktualizujte token.

Generování tokenu

Vygeneruje token, který je platný pro jednu konverzaci.

POST /v3/directline/tokens/generate
Obsah Popis
Text požadavku Objekt TokenParameters
Vrácení Objekt Konverzace

Obnovovací token

Aktualizuje token.

POST /v3/directline/tokens/refresh
Obsah Popis
Text požadavku Není k dispozici
Vrácení Objekt Konverzace

Operace konverzací

Pomocí těchto operací můžete otevřít konverzaci s robotem a vyměňovat si aktivity mezi klientem a robotem.

Operation Popis
Zahájit konverzaci Otevře novou konverzaci s robotem.
Získání informací o konverzaci Získá informace o existující konverzaci. Tato operace vygeneruje novou adresu URL streamu WebSocket, kterou může klient použít k opětovnému připojení ke konverzaci.
Získání aktivit Načte aktivity z robota.
Odeslání aktivity Odešle aktivitu robotovi.
Nahrání a odeslání souborů Nahraje a odešle soubory jako přílohy.

Zahájit konverzaci

Otevře novou konverzaci s robotem.

POST /v3/directline/conversations
Obsah Popis
Text požadavku Objekt TokenParameters
Vrácení Objekt Konverzace

Získání informací o konverzaci

Získá informace o existující konverzaci a také vygeneruje novou adresu URL streamu WebSocket, kterou klient může použít k opětovnému připojení ke konverzaci. Volitelně můžete do identifikátoru watermark URI požadavku zadat parametr, který označuje poslední zprávu zobrazenou klientem.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}
Obsah Popis
Text požadavku Není k dispozici
Vrácení Objekt Konverzace

Získání aktivit

Načte aktivity z robota pro zadanou konverzaci. Volitelně můžete do identifikátoru watermark URI požadavku zadat parametr, který označuje poslední zprávu zobrazenou klientem.

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}
Obsah Popis
Text požadavku Není k dispozici
Vrácení Objekt ActivitySet . Odpověď obsahuje watermark jako vlastnost objektu ActivitySet . Klienti by měli procházet dostupné aktivity tím, že hodnotu posunou watermark , dokud se nevrátí žádné aktivity.

Odeslání aktivity

Odešle aktivitu robotovi.

POST /v3/directline/conversations/{conversationId}/activities
Obsah Popis
Text požadavku Objekt Aktivity
Vrácení A ResourceResponse , která obsahuje id vlastnost, která určuje ID aktivity, která byla odeslána robotovi.

Nahrání a odeslání souborů

Nahraje a odešle soubory jako přílohy. userId Nastavte parametr v identifikátoru URI požadavku tak, aby určil ID uživatele, který odesílá přílohy.

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}
Obsah Popis
Text požadavku U jedné přílohy naplňte text požadavku obsahem souboru. Pro více příloh vytvořte text žádosti s více částmi, který obsahuje jednu část pro každou přílohu, a také (volitelně) jednu část pro objekt Aktivity , který by měl sloužit jako kontejner pro zadané přílohy. Další informace najdete v tématu Odeslání aktivity robotovi.
Vrácení A ResourceResponse , která obsahuje id vlastnost, která určuje ID aktivity, která byla odeslána robotovi.

Poznámka:

Nahrané soubory se odstraní po 24 hodinách.

Schéma

Schéma Direct Line 3.0 zahrnuje všechny objekty, které jsou definovány schématem služby Bot Framework, a také některé objekty specifické pro Direct Line.

Objekt ActivitySet

Definuje sadu aktivit.

Vlastnost Type Popis
Činnosti Aktivita[] Pole objektů aktivity.
Vodoznak string Maximální mez aktivit v rámci sady Klient může použít watermark hodnotu k označení nejnovější zprávy, kterou se zobrazila při načítání aktivit z robota nebo při generování nové adresy URL streamu WebSocket.

Objekt konverzace

Definuje konverzaci direct line.

Vlastnost Type Popis
conversationId string ID, které jednoznačně identifikuje konverzaci, pro kterou je zadaný token platný.
Etag string Značka ETag PROTOKOLU HTTP (značka entity).
expires_in Číslo Počet sekund do vypršení platnosti tokenu
referenceGrammarId string ID referenční gramatiky pro tohoto robota.
streamUrl string Adresa URL streamu zpráv konverzace
Token string Token, který je platný pro zadanou konverzaci.

TokenParameters – objekt

Parametry pro vytvoření tokenu

Vlastnost Type Popis
Etag string Značka ETag PROTOKOLU HTTP (značka entity).
trustedOrigins string[] Důvěryhodné zdroje pro vložení do tokenu.
Uživatel ChannelAccount Uživatelský účet pro vložení do tokenu

Aktivity

Pro každou aktivitu , kterou klient obdrží od robota přes Direct Line:

  • Zachovají se karty příloh.
  • Adresy URL pro nahrané přílohy jsou skryté pomocí privátního odkazu.
  • Vlastnost channelData se zachová beze změny.

Klienti můžou od robota přijímat více aktivit jako součást sady aktivit.

Když klient odešle robotovi přes Activity Direct Line:

  • Vlastnost type určuje aktivitu typu, kterou odesílá (obvykle zpráva).
  • Vlastnost from musí být vyplněna ID uživatele zvoleného klientem.
  • Přílohy můžou obsahovat adresy URL pro existující prostředky nebo adresy URL nahrané prostřednictvím koncového bodu přílohy direct line.
  • Vlastnost channelData se zachová beze změny.
  • Celková velikost aktivity při serializaci do formátu JSON a zašifrování nesmí překročit 256 tisíc znaků. Doporučujeme udržovat aktivity pod 150 tisíc. Pokud potřebujete více dat, zvažte rozdělení aktivity nahoru nebo použití příloh.

Klienti můžou posílat jednu aktivitu na požadavek.

Další materiály