API-Referenz – Direct Line API 1.1

Artikel
03/08/2023

Wichtig

Dieser Artikel enthält Referenzinformationen für Direct Line API 1.1. Wenn Sie eine neue Verbindung zwischen Ihrer Clientanwendung und Ihrem Bot erstellen, verwenden Sie stattdessen Direct Line API 3.0.

Mit Direct Line API 1.1 Sie können Ihre Clientanwendung für die Kommunikation mit Ihrem Bot aktivieren. Direct Line API 1.1 verwendet die Branchenstandards REST und JSON über HTTPS.

Basis-URI

Verwenden Sie für den Zugriff auf Direct Line API 1.1 diesen Basis-URI für alle API-Anforderungen:

https://directline.botframework.com

Header

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. Sie können den Authorization-Header mit dem Schema „Bearer“ oder dem Schema „BotConnector“ angeben.

Bearer-Schema:

Authorization: Bearer SECRET_OR_TOKEN

BotConnector-Schema:

Authorization: BotConnector 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

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.
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 vorzunehmen. Dieser Statuscode tritt häufig aufgrund eines fehlenden oder falsch formatierten `Authorization`-Headers auf.
403	Der Client darf den angeforderten Vorgang nicht ausführen. Dieser Statuscode tritt häufig auf, weil der `Authorization`-Header ein ungültiges Token oder einen ungültigen geheimen Schlüssel angibt.
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	Im Bot ist ein Fehler aufgetreten. Der Bot ist nicht verfügbar oder hat einen Fehler zurückgegeben. Dies ist ein häufig auftretender Fehlercode.

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 /api/tokens/conversation

Inhalt	Beschreibung
Anforderungstext	–
Rückgabe	Eine Zeichenfolge, die das Token darstellt

Aktualisieren eines Tokens

Aktualisiert das Token.

GET /api/tokens/{conversationId}/renew

Inhalt	Beschreibung
Anforderungstext	–
Rückgabe	Eine Zeichenfolge, die das neue Token darstellt

Konversationsvorgänge

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

Vorgang	BESCHREIBUNG
Konversation starten	Startet eine neue Konversation mit dem Bot.
Get Messages	Empfängt Nachrichten vom Bot.
Nachricht senden	Sendet eine Nachricht 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 /api/conversations

Inhalt	Beschreibung
Anforderungstext	–
Rückgabe	Ein Conversation-Objekt.

Nachrichten abrufen

Ruft Nachrichten vom Bot für eine angegebene Konversation ab. Legen Sie den watermark-Parameter im Anforderungs-URI so fest, dass die neueste Nachricht vom Client angezeigt wird.

GET /api/conversations/{conversationId}/messages?watermark={watermark_value}

Inhalt	Beschreibung
Anforderungstext	–
Rückgabe	Ein MessageSet-Objekt. Die Antwort enthält `watermark` als Eigenschaft des `MessageSet`-Objekts. Clients sollten durch die verfügbaren Nachrichten blättern, indem der `watermark`-Wert erhöht wird, bis keine Nachrichten mehr zurückgegeben werden.

Nachricht senden

Sendet eine Nachricht an den Bot.

POST /api/conversations/{conversationId}/messages

Inhalt	Beschreibung
Anforderungstext	Ein Message-Objekt
Rückgabe	Es werden keine Daten im Text der Antwort zurückgegeben. Der Dienst antwortet mit einem Statuscode „HTTP 204“, wenn die Nachricht erfolgreich gesendet wurde. Der Client kann die gesendete Nachricht (zusammen mit allen Nachrichten, die vom Bot an den Client gesendet wurden) mithilfe des Nachrichten abrufen-Vorgangs abrufen.

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 /api/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 Message-Objekt enthält, das als Container für die angegebene(n) Anlage(n) fungieren soll. Weitere Informationen finden Sie unter Senden einer Nachricht an den Bot.
Rückgabe	Es werden keine Daten im Text der Antwort zurückgegeben. Der Dienst antwortet mit einem Statuscode „HTTP 204“, wenn die Nachricht erfolgreich gesendet wurde. Der Client kann die gesendete Nachricht (zusammen mit allen Nachrichten, die vom Bot an den Client gesendet wurden) mithilfe des Nachrichten abrufen-Vorgangs abrufen.

Hinweis

Hochgeladene Dateien werden nach 24 Stunden gelöscht.

Schema

Das Direct Line 1.1-Schema ist eine vereinfachte Kopie des Bot Framework v1-Schemas, das die folgenden Objekte enthält.

Message-Objekt

Definiert eine Nachricht, die ein Client an einen Bot sendet oder von einem Bot empfängt.

Eigenschaft	type	BESCHREIBUNG
id	Zeichenfolge	ID, die die (von Direct Line zugewiesene) Nachricht eindeutig identifiziert.
conversationId	Zeichenfolge	ID, die die Konversation identifiziert.
created	Zeichenfolge	Datum und Uhrzeit, zu der die Nachricht erstellt wurde, ausgedrückt im ISO-8601-Format.
from	Zeichenfolge	ID, die den Benutzer identifiziert, der der Absender der Nachricht ist. Wenn Sie eine Nachricht erstellen, sollten Clients diese Eigenschaft auf eine stabile Benutzer-ID festlegen. Obwohl Direct Line eine Benutzer-ID zuweist, wenn kein Wert angegeben ist, führt dies in der Regel zu unerwartetem Verhalten.
text	Zeichenfolge	Der Text der Nachricht, die vom Benutzer an den Bot oder vom Bot an den Benutzer gesendet wird.
channelData	Objekt (object)	Ein Objekt mit kanalspezifischem Inhalt. Einige Kanäle bieten Features, die zusätzliche Informationen erfordern, die nicht mithilfe des Anlagenschemas dargestellt werden können. Legen Sie für diese Fälle diese Eigenschaft auf den kanalspezifischen Inhalt fest, wie in der Dokumentation des Kanals definiert. Diese Daten werden zwischen Client und Bot unverändert gesendet. Diese Eigenschaft muss entweder auf ein komplexes Objekt festgelegt oder leer gelassen werden. Legen Sie sie nicht auf eine Zeichenfolge, Zahl oder einen anderen einfachen Typ fest.
images	string[]	Array von Zeichenfolgen, das die URL(s) für die Bilder in der Nachricht enthält. In einigen Fällen können Zeichenfolgen in diesem Array relative URLs sein. Wenn eine Zeichenfolge in diesem Array nicht mit "http" oder "https" beginnt, wird die Zeichenfolge vorgestellt, `https://directline.botframework.com` um die vollständige URL zu bilden.
attachments	Attachment[]	Array von Attachment-Objekten, die die in der Nachricht enthaltenen Anlagen ohne Bilder darstellen. Jedes Objekt im Array enthält eine `url`-Eigenschaft und eine `contentType`-Eigenschaft. In Nachrichten, die ein Client von einem Bot erhält, kann die `url`-Eigenschaft möglicherweise manchmal eine relative URL angeben. Für jeden `url` Eigenschaftswert, der nicht mit "http" oder "https" beginnt, wird die Zeichenfolge vorgestellt `https://directline.botframework.com` , um die vollständige URL zu bilden.

Das folgende Beispiel zeigt ein Message-Objekt, das alle möglichen Eigenschaften enthält. In den meisten Fällen beim Erstellen einer Nachricht muss der Client nur die from Eigenschaft und mindestens eine Inhaltseigenschaft (ztext. B. , , imagesattachmentschannelDataoder ).

{
    "id": "CuvLPID4kDb|000000000000000004",
    "conversationId": "CuvLPID4kDb",
    "created": "2016-10-28T21:19:51.0357965Z",
    "from": "examplebot",
    "text": "Hello!",
    "channelData": {
        "examplefield": "abc123"
    },
    "images": [
        "/attachments/CuvLPID4kDb/0.jpg?..."
    ],
    "attachments": [
        {
            "url": "https://example.com/example.docx",
            "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
        }, 
        {
            "url": "https://example.com/example.doc",
            "contentType": "application/msword"
        }
    ]
}

MessageSet-Objekt

Definiert einen Satz von Nachrichten.

Eigenschaft	type	BESCHREIBUNG
messages	Message[]	Array von Message-Objekten.
watermark	Zeichenfolge	Maximales Wasserzeichen von Nachrichten innerhalb des Satzes. Ein Client kann den `watermark`-Wert verwenden, um die letzte beim Abrufen von Nachrichten vom Bot angezeigte Nachricht anzugeben.

Attachment-Objekt

Definiert eine Anlage ohne Bilder.

Eigenschaft	type	BESCHREIBUNG
contentType	Zeichenfolge	Der Medientyp des Inhalts der Anlage.
url	Zeichenfolge	Die URL für den Inhalt der Anlage.

Conversation-Objekt

Definiert eine Direct Line-Konversation.

Eigenschaft	type	BESCHREIBUNG
conversationId	Zeichenfolge	ID, die Konversation, für die das angegebene Token gültig ist, eindeutig identifiziert.
token	Zeichenfolge	Token, das für die angegebene Konversation gültig ist.
expires_in	number	Die Anzahl der Sekunden bis zum Ablauf des Tokens.

Error-Objekt

Definiert einen Fehler.

Eigenschaft	type	BESCHREIBUNG
code	Zeichenfolge	Fehlercode Einer der folgenden Werte: MissingProperty, MalformedData, NotFound, ServiceError, Internal, InvalidRange, NotSupported, NotAllowed, BadCertificate.
Nachricht	Zeichenfolge	Eine Beschreibung des Fehlers.
statusCode	number	Statuscode.

ErrorMessage-Objekt

Fehlernutzlast einer standardisierten Nachricht.

Eigenschaft	type	BESCHREIBUNG
error	Fehler	Ein Error-Objekt mit Informationen zum Fehler.

Freigeben über