Delen via

API-verwijzing - Direct Line API 3.0

  • Artikel

U kunt uw clienttoepassing inschakelen om met uw bot te communiceren met behulp van Direct Line API 3.0. Direct Line API 3.0 maakt gebruik van industriestandaard REST en JSON via HTTPS.

Basis-URI

Voor toegang tot Direct Line API 3.0 gebruikt u een van deze basis-URI's voor alle API-aanvragen:

  • Voor globale bots gebruikt u https://directline.botframework.com

  • Voer voor een regionale bot de volgende URI in volgens de geselecteerde regio:

    Regio Basis-URI
    Europa https://europe.directline.botframework.com
    India https://india.directline.botframework.com

Tip

Een aanvraag kan mislukken als u de globale basis-URI voor een regionale bot gebruikt, omdat sommige aanvragen buiten geografische grenzen kunnen vallen.

Kopteksten

Naast de standaard-HTTP-aanvraagheaders moet een Direct Line-API-aanvraag een Authorization header bevatten die een geheim of token opgeeft om de client te verifiëren die de aanvraag uitgeeft. Geef de Authorization header op met behulp van deze indeling:

Authorization: Bearer SECRET_OR_TOKEN

Zie Verificatie voor meer informatie over het verkrijgen van een geheim of token dat uw client kan gebruiken om de Direct Line API-aanvragen te verifiëren.

HTTP-statuscode

De HTTP-statuscode die met elk antwoord wordt geretourneerd, geeft het resultaat van de bijbehorende aanvraag aan.

HTTP-statuscode Betekenis
200 De aanvraag is voltooid.
201 De aanvraag is voltooid.
202 De aanvraag is geaccepteerd voor verwerking.
204 De aanvraag is voltooid, maar er is geen inhoud geretourneerd.
400 De aanvraag is onjuist of anderszins onjuist.
401 De client is niet gemachtigd om de aanvraag te doen. Deze statuscode treedt vaak op omdat de Authorization header ontbreekt of onjuist is ingedeeld.
403 De client mag de aangevraagde bewerking niet uitvoeren. De bewerking kan om de volgende redenen mislukken.
  • Een ongeldig token: wanneer de aanvraag een token gebruikt dat eerder geldig was, maar is verlopen, wordt de code eigenschap van de fout die wordt geretourneerd in het object ErrorResponse ingesteld TokenExpiredop .
  • Een schending van de gegevensgrens: als uw bot een regionale bot is, maar de basis-URI niet regionaal is, kunnen sommige aanvragen buiten geografische grenzen gaan.
  • Een ongeldige doelresource: de doelbot of -site is ongeldig of is verwijderd.
404 De aangevraagde resource is niet gevonden. Deze statuscode geeft doorgaans een ongeldige aanvraag-URI aan.
500 Er is een interne serverfout opgetreden in de Direct Line-service.
502 De bot is niet beschikbaar of er is een fout geretourneerd. Dit is een veelvoorkomende foutcode.

Notitie

HTTP-statuscode 101 wordt gebruikt in het webSocket-verbindingspad, hoewel dit waarschijnlijk wordt verwerkt door uw WebSocket-client.

Fouten

Elk antwoord dat een HTTP-statuscode in het bereik 4xx of 5xx opgeeft, bevat een ErrorResponse-object in de hoofdtekst van het antwoord dat informatie over de fout bevat. Als u een foutbericht ontvangt in het bereik 4xx, inspecteert u het object ErrorResponse om de oorzaak van de fout te identificeren en het probleem op te lossen voordat u de aanvraag opnieuw indient.

Notitie

HTTP-statuscodes en -waarden die zijn opgegeven in de code eigenschap binnen het object ErrorResponse zijn stabiel. Waarden die zijn opgegeven in de message eigenschap binnen het object ErrorResponse , kunnen na verloop van tijd veranderen.

In de volgende codefragmenten ziet u een voorbeeldaanvraag en het resulterende foutbericht.

Aanvragen

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

Tokenbewerkingen

Gebruik deze bewerkingen om een token te maken of te vernieuwen dat een client kan gebruiken voor toegang tot één gesprek.

Operation Omschrijving
Token genereren Genereer een token voor een nieuw gesprek.
Token vernieuwen Een token vernieuwen.

Token genereren

Hiermee wordt een token gegenereerd dat geldig is voor één gesprek.

POST /v3/directline/tokens/generate
Inhoud Beschrijving
Aanvraagbody Een TokenParameters-object
Retouren Een gespreksobject

Token vernieuwen

Hiermee vernieuwt u het token.

POST /v3/directline/tokens/refresh
Inhoud Beschrijving
Aanvraagbody N.v.t.
Retouren Een gespreksobject

Gespreksbewerkingen

Gebruik deze bewerkingen om een gesprek met uw bot te openen en activiteiten uit te wisselen tussen client en bot.

Operation Omschrijving
Gesprek starten Hiermee opent u een nieuw gesprek met de bot.
Gespreksgegevens ophalen Hiermee haalt u informatie over een bestaand gesprek op. Met deze bewerking wordt een nieuwe WebSocket-stream-URL gegenereerd die een client kan gebruiken om opnieuw verbinding te maken met een gesprek.
Activiteiten ophalen Hiermee worden activiteiten opgehaald uit de bot.
Een activiteit verzenden Hiermee wordt een activiteit naar de bot verzonden.
Bestand(en) uploaden en verzenden Uploadt en verzendt een of meer bestanden als bijlagen.

Gesprek starten

Hiermee opent u een nieuw gesprek met de bot.

POST /v3/directline/conversations
Inhoud Beschrijving
Aanvraagbody Een TokenParameters-object
Retouren Een gespreksobject

Gespreksgegevens ophalen

Haalt informatie op over een bestaand gesprek en genereert ook een nieuwe WebSocket-stream-URL die een client kan gebruiken om opnieuw verbinding te maken met een gesprek. U kunt eventueel de watermark parameter opgeven in de aanvraag-URI om het meest recente bericht aan te geven dat door de client wordt weergegeven.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}
Inhoud Beschrijving
Aanvraagbody N.v.t.
Retouren Een gespreksobject

Activiteiten ophalen

Hiermee worden activiteiten opgehaald uit de bot voor het opgegeven gesprek. U kunt eventueel de watermark parameter opgeven in de aanvraag-URI om het meest recente bericht aan te geven dat door de client wordt weergegeven.

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}
Inhoud Beschrijving
Aanvraagbody N.v.t.
Retouren Een ActivitySet-object . Het antwoord bevat watermark als een eigenschap van het ActivitySet object. Clients moeten door de beschikbare activiteiten bladeren door de watermark waarde door te voeren totdat er geen activiteiten worden geretourneerd.

Een activiteit verzenden

Hiermee wordt een activiteit naar de bot verzonden.

POST /v3/directline/conversations/{conversationId}/activities
Inhoud Beschrijving
Aanvraagbody Een activiteitsobject
Retouren Een ResourceResponse die een id eigenschap bevat die de id aangeeft van de activiteit die naar de bot is verzonden.

Bestand(en) uploaden en verzenden

Uploadt en verzendt een of meer bestanden als bijlagen. Stel de userId parameter in de aanvraag-URI in om de id op te geven van de gebruiker die de bijlagen verzendt.

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}
Inhoud Beschrijving
Aanvraagbody Vul voor één bijlage de hoofdtekst van de aanvraag in met de bestandsinhoud. Voor meerdere bijlagen maakt u een aanvraagbody met meerdere onderdelen die één deel voor elke bijlage bevat, en (optioneel) één onderdeel voor het activiteitsobject dat als container voor de opgegeven bijlagen moet fungeren. Zie Een activiteit naar de bot verzenden voor meer informatie.
Retouren Een ResourceResponse die een id eigenschap bevat die de id aangeeft van de activiteit die naar de bot is verzonden.

Notitie

Geüploade bestanden worden na 24 uur verwijderd.

Schema

Het schema Direct Line 3.0 bevat alle objecten die zijn gedefinieerd door het Bot Framework-schema , evenals enkele objecten die specifiek zijn voor Direct Line.

ActivitySet-object

Hiermee definieert u een set activiteiten.

Eigenschap Type Description
Activiteiten Activiteit[] Matrix van activiteitsobjecten .
Watermerk tekenreeks Maximumwatermerk van activiteiten binnen de set. Een client kan de watermark waarde gebruiken om het meest recente bericht aan te geven dat het heeft gezien bij het ophalen van activiteiten van de bot of bij het genereren van een nieuwe WebSocket-stream-URL.

Gespreksobject

Hiermee definieert u een Direct Line-gesprek.

Eigenschap Type Description
conversationId tekenreeks Id waarmee het gesprek uniek wordt geïdentificeerd waarvoor het opgegeven token geldig is.
eTag tekenreeks Een HTTP ETag (entiteitstag).
expires_in Nummer Aantal seconden totdat het token verloopt.
referenceGrammarId tekenreeks Id voor de referentie grammatica voor deze bot.
streamUrl tekenreeks URL voor de berichtstroom van het gesprek.
token tekenreeks Token dat geldig is voor het opgegeven gesprek.

TokenParameters-object

Parameters voor het maken van een token.

Eigenschap Type Description
eTag tekenreeks Een HTTP ETag (entiteitstag).
trustedOrigins tekenreeks[] Vertrouwde oorsprongen die binnen het token moeten worden ingesloten.
gebruiker ChannelAccount Gebruikersaccount dat moet worden ingesloten in het token.

Activiteiten

Voor elke activiteit die een client van een bot ontvangt via Direct Line:

  • Bijlagekaarten blijven behouden.
  • URL's voor geüploade bijlagen zijn verborgen met een privékoppeling.
  • De channelData eigenschap blijft behouden zonder wijziging.

Clients kunnen meerdere activiteiten van de bot ontvangen als onderdeel van een ActivitySet.

Wanneer een client een Activity naar een bot verzendt via Direct Line:

  • De type eigenschap geeft de typeactiviteit op die wordt verzonden (meestal bericht).
  • De from eigenschap moet worden ingevuld met een gebruikers-id, gekozen door de client.
  • Bijlagen kunnen URL's bevatten naar bestaande resources of URL's die zijn geüpload via het eindpunt van de Direct Line-bijlage.
  • De channelData eigenschap blijft behouden zonder wijziging.
  • De totale grootte van de activiteit, wanneer deze wordt geserialiseerd naar JSON en versleuteld, mag niet langer zijn dan 256.000 tekens. We raden u aan activiteiten onder de 150.000 te houden. Als er meer gegevens nodig zijn, kunt u overwegen om de activiteit op te splitsen of bijlagen te gebruiken.

Clients kunnen één activiteit per aanvraag verzenden .

Aanvullende bronnen