Dela via

API-referens – Direct Line API 3.0

  • Artikel

Du kan göra så att klientprogrammet kommunicerar med din robot med hjälp av Direct Line API 3.0. Direct Line API 3.0 använder branschstandard-REST och JSON via HTTPS.

Bas-URI

Om du vill komma åt Direct Line API 3.0 använder du någon av dessa bas-URI:er för alla API-begäranden:

  • För globala robotar använder du https://directline.botframework.com

  • För en regional robot anger du följande URI enligt den valda regionen:

    Region Bas-URI
    Europa https://europe.directline.botframework.com
    Indien https://india.directline.botframework.com

Dricks

En begäran kan misslyckas om du använder den globala bas-URI:n för en regional robot, eftersom vissa begäranden kan överskrida geografiska gränser.

Sidhuvuden

Förutom standardrubrikerna för HTTP-begäran måste en API-begäran för direktrad innehålla ett Authorization huvud som anger en hemlighet eller token för att autentisera klienten som utfärdar begäran. Authorization Ange rubriken med det här formatet:

Authorization: Bearer SECRET_OR_TOKEN

Mer information om hur du hämtar en hemlighet eller token som klienten kan använda för att autentisera sina API-begäranden för direct line finns i Autentisering.

HTTP-statuskoder

HTTP-statuskoden som returneras med varje svar anger resultatet av motsvarande begäran.

HTTP-statuskod Innebörd
200 Begäran lyckades.
201 Begäran lyckades.
202 Begäran har godkänts för bearbetning.
204 Begäran lyckades men inget innehåll returnerades.
400 Begäran var felaktigt eller på annat sätt felaktig.
401 Klienten har inte behörighet att göra begäran. Ofta inträffar den här statuskoden eftersom Authorization rubriken saknas eller är felaktigt formaterad.
403 Klienten kan inte utföra den begärda åtgärden. Åtgärden kan misslyckas av följande skäl.
  • En ogiltig token: när begäran använder en token som tidigare var giltig men har upphört att gälla, code är egenskapen för felet som returneras i ErrorResponse-objektet inställd på TokenExpired.
  • En datagränsöverträdelse: om din robot är en regional robot, men bas-URI:n inte är regional, kan vissa begäranden gå utanför geografiska gränser.
  • En ogiltig målresurs: målroboten eller webbplatsen är ogiltig eller har tagits bort.
404 Den begärda resursen hittades inte. Den här statuskoden anger vanligtvis en ogiltig URI för begäran.
500 Ett internt serverfel uppstod i direct line-tjänsten.
502 Roboten är inte tillgänglig eller returnerade ett fel. Det här är en vanlig felkod.

Kommentar

HTTP-statuskod 101 används i WebbSocket-anslutningssökvägen, även om detta troligen hanteras av WebSocket-klienten.

Fel

Alla svar som anger en HTTP-statuskod i intervallet 4xx eller 5xx innehåller ett ErrorResponse-objekt i brödtexten i svaret som innehåller information om felet. Om du får ett felsvar i 4xx-intervallet kontrollerar du ErrorResponse-objektet för att identifiera orsaken till felet och lösa problemet innan du skickar begäran igen.

Kommentar

HTTP-statuskoder och värden som anges i code egenskapen i ErrorResponse-objektet är stabila. Värden som anges i message egenskapen i ErrorResponse-objektet kan ändras över tid.

Följande kodfragment visar en exempelbegäran och det resulterande felsvaret.

Begär

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

Tokenåtgärder

Använd dessa åtgärder för att skapa eller uppdatera en token som en klient kan använda för att komma åt en enda konversation.

Operation beskrivning
Generera token Generera en token för en ny konversation.
Uppdateringstoken Uppdatera en token.

Generera token

Genererar en token som är giltig för en konversation.

POST /v3/directline/tokens/generate
Innehåll beskrivning
Begärandetext Ett TokenParameters-objekt
Returer Ett konversationsobjekt

Uppdateringstoken

Uppdaterar token.

POST /v3/directline/tokens/refresh
Innehåll beskrivning
Begärandetext saknas
Returer Ett konversationsobjekt

Konversationsåtgärder

Använd dessa åtgärder för att öppna en konversation med din robot och utbyta aktiviteter mellan klient och robot.

Operation beskrivning
Starta konversation Öppnar en ny konversation med roboten.
Hämta konversationsinformation Hämtar information om en befintlig konversation. Den här åtgärden genererar en ny Url för WebSocket-dataström som en klient kan använda för att återansluta till en konversation.
Hämta aktiviteter Hämtar aktiviteter från roboten.
Skicka en aktivitet Skickar en aktivitet till roboten.
Ladda upp och skicka filer Laddar upp och skickar filer som bifogade filer.

Starta konversation

Öppnar en ny konversation med roboten.

POST /v3/directline/conversations
Innehåll beskrivning
Begärandetext Ett TokenParameters-objekt
Returer Ett konversationsobjekt

Hämta konversationsinformation

Hämtar information om en befintlig konversation och genererar även en ny WebSocket-ström-URL som en klient kan använda för att återansluta till en konversation. Du kan också ange parametern watermark i begärande-URI:n för att ange det senaste meddelandet som visas av klienten.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}
Innehåll beskrivning
Begärandetext saknas
Returer Ett konversationsobjekt

Hämta aktiviteter

Hämtar aktiviteter från roboten för den angivna konversationen. Du kan också ange parametern watermark i begärande-URI:n för att ange det senaste meddelandet som visas av klienten.

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}
Innehåll beskrivning
Begärandetext saknas
Returer Ett ActivitySet-objekt . Svaret innehåller watermark som en egenskap för ActivitySet objektet. Klienter bör gå igenom de tillgängliga aktiviteterna watermark genom att flytta fram värdet tills inga aktiviteter returneras.

Skicka en aktivitet

Skickar en aktivitet till roboten.

POST /v3/directline/conversations/{conversationId}/activities
Innehåll beskrivning
Begärandetext Ett aktivitetsobjekt
Returer En ResourceResponse som innehåller en id egenskap som anger ID för aktiviteten som skickades till roboten.

Ladda upp och skicka filer

Laddar upp och skickar filer som bifogade filer. Ange parametern userId i begärande-URI:n för att ange ID för den användare som skickar de bifogade filerna.

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}
Innehåll beskrivning
Begärandetext Fyll i begärandetexten med filinnehållet för en enda bifogad fil. För flera bifogade filer skapar du en brödtext för begäranden med flera delar som innehåller en del för varje bifogad fil, och även (valfritt) en del för aktivitetsobjektet som ska fungera som container för de angivna bifogade filerna. Mer information finns i Skicka en aktivitet till roboten.
Returer En ResourceResponse som innehåller en id egenskap som anger ID för aktiviteten som skickades till roboten.

Kommentar

Uppladdade filer tas bort efter 24 timmar.

Schema

Direct Line 3.0-schemat innehåller alla objekt som definieras av Bot Framework-schemat samt vissa objekt som är specifika för Direct Line.

ActivitySet-objekt

Definierar en uppsättning aktiviteter.

Property Type Beskrivning
Aktiviteter Aktivitet[] Matris med aktivitetsobjekt.
Vattenstämpel sträng Maximal vattenstämpel för aktiviteter i uppsättningen. En klient kan använda watermark värdet för att ange det senaste meddelandet som den har sett när den hämtar aktiviteter från roboten eller när en ny WebSocket-ström-URL genereras.

Konversationsobjekt

Definierar en direktradskonversation.

Property Type Beskrivning
conversationId sträng ID som unikt identifierar konversationen som den angivna token är giltig för.
Etag sträng En HTTP ETag (entitetstagg).
expires_in Nummer Antal sekunder tills token upphör att gälla.
referenceGrammarId sträng ID för referens grammatik för den här roboten.
streamUrl sträng URL för konversationens meddelandeström.
Token sträng Token som är giltig för den angivna konversationen.

TokenParameters-objekt

Parametrar för att skapa en token.

Property Type Beskrivning
Etag sträng En HTTP ETag (entitetstagg).
trustedOrigins string[] Betrott ursprung som ska bäddas in i token.
användare ChannelAccount Användarkonto som ska bäddas in i token.

Aktiviteter

För varje aktivitet som en klient tar emot från en robot via Direct Line:

  • Bifogade kort bevaras.
  • URL:er för uppladdade bifogade filer är dolda med en privat länk.
  • Egenskapen channelData bevaras utan ändringar.

Klienter kan ta emot flera aktiviteter från roboten som en del av en ActivitySet.

När en klient skickar en Activity till en robot via Direct Line:

  • Egenskapen type anger vilken typaktivitet den skickar (vanligtvis meddelande).
  • Egenskapen from måste fyllas i med ett användar-ID som väljs av klienten.
  • Bifogade filer kan innehålla URL:er till befintliga resurser eller URL:er som laddats upp via slutpunkten för direktradsbilagor.
  • Egenskapen channelData bevaras utan ändringar.
  • Aktivitetens totala storlek, när den serialiseras till JSON och krypteras, får inte överstiga 256 000 tecken. Vi rekommenderar att du behåller aktiviteter under 150 000. Om du behöver mer data kan du överväga att dela upp aktiviteten eller använda bifogade filer.

Klienter kan skicka en enskild aktivitet per begäran.

Ytterligare resurser