API-Referenz – Direct Line API 3.0

Sie können ihre Clientanwendung für die Kommunikation mit Ihrem Bot aktivieren, indem Sie Direct Line API 3.0 verwenden. Direct Line API 3.0 verwendet Branchenstandard REST und JSON über HTTPS.

Basis-URL

Verwenden Sie eine der folgenden Basis-URIs für alle API-Anforderungen, um auf Direct Line API 3.0 zuzugreifen:

  • Verwenden Sie für globale Bots https://directline.botframework.com

  • Geben Sie für einen regionalen Bot den folgenden URI gemäß der ausgewählten Region ein:

    Region Basis-URL
    Europe https://europe.directline.botframework.com
    India https://india.directline.botframework.com

Tip

Eine Anforderung schlägt möglicherweise fehl, wenn Sie den globalen Basis-URI für einen regionalen Bot verwenden, da einige Anforderungen über geografische Grenzen hinausgehen können.

Headers

Zusätzlich zu den standardmäßigen HTTP-Anforderungsheadern muss eine Direct Line-API-Anforderung einen Authorization Header enthalten, der einen geheimen Schlüssel oder ein Token angibt, um den Client zu authentifizieren, der die Anforderung ausgibt. Geben Sie die Authorization Kopfzeile mit diesem Format an:

Authorization: Bearer SECRET_OR_TOKEN

Ausführliche Informationen zum Abrufen eines geheimen Schlüssels oder Tokens, den Ihr Client zum Authentifizieren seiner Direct Line API-Anforderungen verwenden kann, finden Sie unter "Authentifizierung".

HTTP-Statuscodes

Der HTTP-Statuscode , der mit jeder Antwort zurückgegeben wird, gibt das Ergebnis der entsprechenden Anforderung an.

HTTP-Statuscode Bedeutung
200 Die Anfrage war erfolgreich.
201 Die Anfrage war erfolgreich.
202 Der Antrag wurde zur Bearbeitung angenommen.
204 Die Anforderung war erfolgreich, aber es wurden keine Inhalte zurückgegeben.
400 Die Anforderung war falsch formatiert oder anderweitig falsch.
401 Der Client ist nicht berechtigt, die Anforderung zu stellen. Dieser Statuscode tritt häufig auf, da die Authorization Kopfzeile fehlt oder falsch formatiert ist.
403 Der Client darf den angeforderten Vorgang nicht ausführen. Der Vorgang kann aus den folgenden Gründen fehlschlagen.
  • Ein ungültiges Token: Wenn die Anforderung ein Token verwendet, das zuvor gültig war, aber abgelaufen ist, wird die code Eigenschaft des Fehlers , der im ErrorResponse-Objekt zurückgegeben wird, auf TokenExpiredfestgelegt.
  • Eine Datenbegrenzungsverletzung: Wenn Ihr Bot ein regionaler Bot ist, aber der Basis-URI nicht regional ist, gehen einige Anforderungen möglicherweise über geografische Grenzen hinaus.
  • Eine ungültige Zielressource: Der Zielbot oder die Zielwebsite ist ungültig oder wurde gelöscht.
404 Die angeforderte Ressource wurde nicht gefunden. In der Regel gibt dieser Statuscode einen ungültigen Anforderungs-URI an.
500 Innerhalb des Direct Line Diensts ist ein interner Serverfehler aufgetreten.
502 Der Bot ist nicht verfügbar oder hat einen Fehler zurückgegeben. Dies ist ein gängiger Fehlercode.

Note

HTTP-Statuscode 101 wird im WebSocket-Verbindungspfad verwendet, obwohl dies wahrscheinlich von Ihrem WebSocket-Client behandelt wird.

Errors

Jede Antwort, die einen HTTP-Statuscode im 4xx-Bereich oder 5xx-Bereich angibt, enthält ein ErrorResponse-Objekt im Textkörper der Antwort, der Informationen zum Fehler bereitstellt. Wenn Sie eine Fehlerantwort im 4xx-Bereich erhalten, überprüfen Sie das ErrorResponse-Objekt , um die Ursache des Fehlers zu identifizieren und das Problem zu beheben, bevor Sie die Anforderung erneut übermitteln.

Note

HTTP-Statuscodes und -Werte, die in der code Eigenschaft innerhalb des ErrorResponse-Objekts angegeben sind, sind stabil. Werte, die in der message Eigenschaft innerhalb des ErrorResponse-Objekts angegeben sind, können sich im Laufe der Zeit ändern.

Die folgenden Codeausschnitte zeigen eine Beispielanforderung und die resultierende Fehlerantwort.

Anforderung

POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
[detail omitted]

Antwort

HTTP/1.1 502 Bad Gateway
[other headers]

{
    "error": {
        "code": "BotRejectedActivity",
        "message": "Failed to send activity: bot returned an error"
    }
}

Tokenvorgänge

Verwenden Sie diese Vorgänge, um ein Token zu erstellen oder zu aktualisieren, das ein Client für den Zugriff auf eine einzelne Unterhaltung verwenden kann.

Vorgang Description
Token generieren Generieren Sie ein Token für eine neue Unterhaltung.
Aktualisierungstoken Aktualisieren sie ein Token.

Token generieren

Generiert ein Token, das für eine Unterhaltung gültig ist.

POST /v3/directline/tokens/generate
Content Description
Anforderungstext Ein TokenParameters-Objekt
Rückgabe Ein Conversation-Objekt

Token aktualisieren

Aktualisiert das Token.

POST /v3/directline/tokens/refresh
Content Description
Anforderungstext n/a
Rückgabe Ein Conversation-Objekt

Unterhaltungsvorgänge

Verwenden Sie diese Vorgänge, um eine Unterhaltung mit Ihrem Bot zu öffnen und Aktivitäten zwischen Client und Bot auszutauschen.

Vorgang Description
Unterhaltung starten Öffnet eine neue Unterhaltung mit dem Bot.
Abrufen von Unterhaltungsinformationen Ruft Informationen zu einer vorhandenen Unterhaltung ab. Dieser Vorgang generiert eine neue WebSocket-Stream-URL, die ein Client zum erneuten Herstellen einer Verbindung mit einer Unterhaltung verwenden kann.
Aktivitäten abrufen Ruft Aktivitäten vom Bot ab.
Senden einer Aktivität Sendet eine Aktivität an den Bot.
Hochladen und Senden von Dateien Lädt(n) Dateien als Anlagen hoch und sendet sie.

Starte ein Gespräch

Öffnet eine neue Unterhaltung mit dem Bot.

POST /v3/directline/conversations
Content Description
Anforderungstext Ein TokenParameters-Objekt
Rückgabe Ein Conversation-Objekt

Abrufen von Unterhaltungsinformationen

Ruft Informationen zu einer vorhandenen Unterhaltung ab und generiert auch eine neue WebSocket-Stream-URL, die ein Client zum erneuten Herstellen einer Verbindung mit einer Unterhaltung verwenden kann. Sie können optional den watermark Parameter im Anforderungs-URI angeben, um die zuletzt vom Client angezeigte Nachricht anzugeben.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}
Content Description
Anforderungstext n/a
Rückgabe Ein Conversation-Objekt

Aktivitäten abrufen

Ruft Aktivitäten vom Bot für die angegebene Unterhaltung ab. Sie können optional den watermark Parameter im Anforderungs-URI angeben, um die zuletzt vom Client angezeigte Nachricht anzugeben.

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}
Content Description
Anforderungstext n/a
Rückgabe Ein ActivitySet-Objekt . Die Antwort enthält watermark als Eigenschaft des ActivitySet Objekts. Clients sollten durch die verfügbaren Aktivitäten blättern, indem sie den watermark Wert voranbringen, bis keine Aktivitäten zurückgegeben werden.

Senden einer Aktivität

Sendet eine Aktivität an den Bot.

POST /v3/directline/conversations/{conversationId}/activities
Content Description
Anforderungstext Ein Activity-Objekt
Rückgabe Eine ResourceResponse , die eine id Eigenschaft enthält, die die ID der Aktivität angibt, die an den Bot gesendet wurde.

Hochladen und Senden von Dateien

Lädt(n) Dateien als Anlagen hoch und sendet sie. Legen Sie den userId Parameter im Anforderungs-URI fest, um die ID des Benutzers anzugeben, der die Anlagen sendet.

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}
Content Description
Anforderungstext Füllen Sie für eine einzelne Anlage den Anforderungstext mit dem Dateiinhalt auf. Erstellen Sie für mehrere Anlagen einen mehrteiligen Anforderungstext, der einen Teil für jede Anlage enthält, und (optional) einen Teil für das Activity-Objekt , der als Container für die angegebenen Anlagen dienen soll. Weitere Informationen finden Sie unter Senden einer Aktivität an den Bot.
Rückgabe Eine ResourceResponse , die eine id Eigenschaft enthält, die die ID der Aktivität angibt, die an den Bot gesendet wurde.

Note

Hochgeladene Dateien werden nach 24 Stunden gelöscht.

Schema

Das Direct Line 3.0-Schema enthält alle Objekte, die vom Bot Framework-Schema definiert sind, sowie einige Objekte, die für Direct Line spezifisch sind.

ActivitySet-Objekt

Definiert eine Gruppe von Aktivitäten.

Property Typ Description
Aktivitäten Activity[] Array von Activity-Objekten .
Wasserzeichen string Maximales Wasserzeichen von Aktivitäten innerhalb des Satzes. Ein Client kann den watermark Wert verwenden, um die neueste Nachricht anzugeben, die er beim Abrufen von Aktivitäten vom Bot oder beim Generieren einer neuen WebSocket-Stream-URL gesehen hat.

Conversation-Objekt

Definiert eine Direct Line Unterhaltung.

Property Typ Description
conversationId string ID, die die Unterhaltung eindeutig identifiziert, für die das angegebene Token gültig ist.
ETag string Ein HTTP-ETag (Entitätstag).
expires_in Zahl Die Anzahl der Sekunden, bis das Token abläuft.
referenceGrammarId string ID für die Referenzgrammatik für diesen Bot.
streamUrl string URL für den Nachrichtenstream der Unterhaltung.
token string Token, das für die angegebene Unterhaltung gültig ist.

TokenParameters-Objekt

Parameter zum Erstellen eines Tokens.

Property Typ Description
ETag string Ein HTTP-ETag (Entitätstag).
trustedOrigins string[] Vertrauenswürdige Ursprünge, die in das Token eingebettet werden sollen.
user ChannelAccount Benutzerkonto, das in das Token eingebettet werden soll.

Aktivitäten

Für jede Aktivität, die ein Client über Direct Line von einem Bot empfängt:

  • Anlagenkarten bleiben erhalten.
  • URLs für hochgeladene Anlagen werden mit einem privaten Link ausgeblendet.
  • Die channelData Eigenschaft wird ohne Änderung beibehalten.

Clients können mehrere Aktivitäten vom Bot als Teil eines ActivitySetserhalten.

Wenn ein Client einen Activity Bot über Direct Line an einen Bot sendet:

  • Die type Eigenschaft gibt die Typaktivität an, die gesendet wird (in der Regel Nachricht).
  • Die from Eigenschaft muss mit einer Benutzer-ID aufgefüllt werden, die vom Client ausgewählt wird.
  • Anlagen können URLs zu vorhandenen Ressourcen oder URLs enthalten, die über den Direct Line Anlagenendpunkt hochgeladen wurden.
  • Die channelData Eigenschaft wird ohne Änderung beibehalten.
  • Die Gesamtgröße der Aktivität, wenn sie in JSON serialisiert und verschlüsselt ist, darf 256K-Zeichen nicht überschreiten. Es wird empfohlen, Aktivitäten unter 150K zu halten. Wenn weitere Daten erforderlich sind, sollten Sie die Aktivität aufteilen oder Anlagen verwenden.

Clients können eine einzelne Aktivität pro Anforderung senden .

Weitere Ressourcen

  • Last updated on