Referenz zur Direct Line-API 3.0

  • Artikel

Mit der Direct Line-API 3.0 kann Ihre Clientanwendung mit Ihrem Bot kommunizieren. Die Direct Line-API 3.0 verwendet die Branchenstandards REST und JSON über HTTPS.

Basis-URI

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

Tipp

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 Standard-HTTP-Anforderungsheadern muss eine Direct Line-API-Anforderung einen Authorization-Header enthalten, der einen Geheimnis oder ein Token zum Authentifizieren des Clients angibt, der die Anforderung sendet. Geben Sie den Authorization-Header im folgenden Format an:

Authorization: Bearer SECRET_OR_TOKEN

Ausführliche Informationen zum Abrufen eines Geheimnisses oder eines Tokens, mit denen der Client seine Direct Line-API-Anforderungen authentifizieren kann, finden Sie unter Authentifizierung.

HTTP-Statuscodes (Azure Cognitive Search)

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

HTTP-Statuscode Bedeutung
200 Die Anforderung war erfolgreich.
201 Die Anforderung war erfolgreich.
202 Die Anforderung wurde für die Verarbeitung akzeptiert.
204 Die Anforderung war erfolgreich, aber es wurden keine Inhalte zurückgegeben.
400 Die Anforderung war falsch formatiert oder auf andere Weise fehlerhaft.
401 Der Client ist nicht berechtigt, die Anforderung zu stellen. Dieser Statuscode tritt häufig aufgrund eines fehlenden oder falsch formatierten Authorization-Headers auf.
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 innerhalb des ErrorResponse -Objekts 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 weist dieser Statuscode auf einen ungültigen Anforderungs-URI hin.
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 häufig auftretender Fehlercode.

Hinweis

Der HTTP-Statuscode 101 wird für den WebSocket-Verbindungspfad verwendet. Vermutlich wird der Code jedoch von Ihrem WebSocket-Client verarbeitet.

Fehler

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

Hinweis

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

In den folgenden Codeausschnitten wird eine Beispielanforderung und die resultierende Fehlermeldung gezeigt.

Anfordern

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 zum Erstellen oder Aktualisieren eines Tokens, mit dessen Hilfe ein Client auf eine einzelne Konversationen zugreifen kann.

Vorgang Beschreibung
Token generieren Generiert ein Token für eine neue Konversation.
Token aktualisieren Aktualisiert ein Token.

Generieren eines Tokens

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

POST /v3/directline/tokens/generate
Inhalt Beschreibung
Anforderungstext Ein TokenParameters-Objekt.
Rückgabe Ein Conversation-Objekt.

Aktualisieren eines Tokens

Aktualisiert das Token.

POST /v3/directline/tokens/refresh
Inhalt Beschreibung
Anforderungstext –
Rückgabe Ein Conversation-Objekt.

Konversationsvorgänge

Mit den folgenden Vorgängen starten Sie eine Konversation mit Ihrem Bot und tauschen Aktivitäten zwischen Client und Bot aus.

Vorgang Beschreibung
Konversation starten Startet eine neue Konversation mit dem Bot.
Konversationsinformationen abrufen Ruft Informationen zu einer vorhandenen Konversation ab. Dieser Vorgang generiert eine WebSocket-Stream-URL, mit denen ein Client erneut eine Verbindung zu einer Konversation herstellen kann.
Aktivitäten abrufen Ruft Aktivitäten des Bots ab.
Aktivität senden Sendet eine Aktivität an den Bot.
Datei(en) hochladen und senden Lädt Dateien hoch und sendet sie als Anlagen.

Starten einer Konversation

Startet eine neue Konversation mit dem Bot.

POST /v3/directline/conversations
Inhalt Beschreibung
Anforderungstext Ein TokenParameters-Objekt.
Rückgabe Ein Conversation-Objekt.

Abrufen von Konversationsinformationen

Ruft Informationen zu einer vorhandenen Konversation ab und generiert eine neue WebSocket-Stream-URL, mit der ein Client erneut eine Verbindung zu einer Konversation herstellen kann. Sie können den watermark-Parameter im Anforderungs-URI optional so festlegen, dass die neueste Nachricht vom Client angezeigt wird.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}
Inhalt Beschreibung
Anforderungstext –
Rückgabe Ein Conversation-Objekt.

Abrufen von Aktivitäten

Ruft Aktivitäten vom Bot für die angegebene Konversation ab. Sie können den watermark-Parameter im Anforderungs-URI optional so festlegen, dass die neueste Nachricht vom Client angezeigt wird.

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}
Inhalt Beschreibung
Anforderungstext –
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 der watermark-Wert erhöht wird, bis keine Aktivitäten mehr zurückgegeben werden.

Senden einer Aktivität

Sendet eine Aktivität an den Bot.

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

Datei(en) hochladen und senden

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

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

Hinweis

Hochgeladene Dateien werden nach 24 Stunden gelöscht.

Schema

Das Direct Line 3.0-Schema umfasst alle Objekte, die im Bot Framework-Schema definiert sind, sowie einige Direct Line-spezifische Objekte.

ActivitySet-Objekt

Definiert eine Aktivitätenmenge.

Eigenschaft Typ Beschreibung
Aktivitäten Activity[] Array von Aktivität-Objekten.
watermark Zeichenfolge Maximaler Wasserzeichenwert für Aktivitäten innerhalb der Menge. Ein Client kann mit dem watermark-Wert beim Abrufen von Aktivitäten des Bots oder beim Erstellen einer WebSocket-Stream-URL die neueste Nachricht kennzeichnen.

Conversation-Objekt

Definiert eine Direct Line-Konversation.

Eigenschaft Typ Beschreibung
conversationId Zeichenfolge ID, die Konversation, für die das angegebene Token gültig ist, eindeutig identifiziert.
eTag Zeichenfolge Ein HTTP-ETag (Entitätstag).
expires_in Zahl Die Anzahl der Sekunden bis zum Ablauf des Tokens.
referenceGrammarId Zeichenfolge ID für die Verweisgrammatik für diesen Bot.
streamUrl Zeichenfolge URL für den Nachrichtendatenstrom der Konversation.
token Zeichenfolge Token, das für die angegebene Konversation gültig ist.

TokenParameters-Objekt

Parameter für die Tokenerstellung.

Eigenschaft Typ BESCHREIBUNG
eTag Zeichenfolge Ein HTTP-ETag (Entitätstag).
trustedOrigins string[] Vertrauenswürdige Ursprünge, die in das Token eingebettet werden sollen.
Benutzer ChannelAccount Das Benutzerkonto, das in das Token eingebettet werden soll.

Aktivitäten

Für jedes Activity-Objekt, das ein Client von einem Bot über Direct Line erhält, gilt Folgendes:

  • Anlagekarten werden beibehalten.
  • URLs für hochgeladene Anhänge werden mithilfe eines privaten Links anonymisiert.
  • Die channelData-Eigenschaft wird gespeichert, ohne dass Änderungen an ihr vorgenommen werden.

Clients können mehrere Aktivitäten eines Bot als Teil eines ActivitySet-Objekts enthalten.

Wenn ein Client ein Activity-Objekt über Direct Line an den Bot sendet, gilt Folgendes:

  • Die type Eigenschaft gibt die Typaktivität an, die gesendet wird (in der Regel Nachricht).
  • Für die from-Eigenschaft muss automatisch eine vom Client ausgewählte Benutzer-ID festgelegt werden.
  • Anlagen können URLs zu vorhandenen Ressourcen oder URLs enthalten, die über den Direct Line-Anlageendpunkt hochgeladen wurden.
  • Die channelData-Eigenschaft wird gespeichert, ohne dass Änderungen an ihr vorgenommen werden.
  • Die Gesamtgröße der Aktivität darf bei der Serialisierung und Verschlüsselung für JSON 256.000 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 pro Anforderung eine einzelne Aktivität senden.

Zusätzliche Ressourcen