Senden einer Aktivität an den Bot in Direct Line API 3.0
Mit dem Direct Line 3.0-Protokoll können Clients und Bots verschiedene Arten von Aktivitäten austauschen, einschließlich message-Aktivitäten, typing-Aktivitäten und benutzerdefinierte Aktivitäten, die der Bot unterstützt. Ein Client kann eine einzelne Aktivität pro Anforderung senden.
Senden einer Aktivität
Um eine Aktivität an den Bot zu senden, muss der Client ein Aktivität-Objekt erstellen, um die Aktivität zu definieren, und dann an https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities eine POST-Anforderung mit dem Activity-Objekt im Text der Anforderung ausgeben.
Die folgenden Codeausschnitte enthalten ein Beispiel der Send Activity-Anforderung und -Antwort.
Anforderung
POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: application/json
[other headers]
{
"locale": "en-EN",
"type": "message",
"from": {
"id": "user1"
},
"text": "hello"
}
Antwort
Wenn die Aktivität an den Bot übermittelt wird, antwortet der Dienst mit einem HTTP-Statuscode, der den Statuscode des Bots widerspiegelt. Wenn der Bot einen Fehler generiert, wird eine HTTP 502-Antwort („Ungültiges Gateway“) als Antwort auf eine die Send Activity-Anforderung an den Client zurückgegeben.
Hinweis
Dies kann durch die Tatsache verursacht werden, dass ein richtiges Token nicht verwendet wurde. Zum Senden einer Aktivität kann ausschließlich das Token verwendet werden, das für den Vorgang Konversation starten empfangen wurde.
Wenn das Senden (POST) erfolgreich ist, enthält die Antwort eine JSON-Nutzlast, die die ID der Aktivität angibt, die an den Bot gesendet wurde.
HTTP/1.1 200 OK
[other headers]
{
"id": "0001"
}
Gesamtzeit für die Send Activity-Anforderung/Antwort
Die Gesamtzeit zum Senden (POST) einer Nachricht an eine Direct Line-Konversation ist die Summe aus folgenden Zeiten:
- Übertragungszeit der Übermittlung der HTTP-Anforderung vom Client an den Direct Line-Dienst
- Interne Verarbeitungszeit in Direct Line (in der Regel weniger als 120ms)
- Übertragungszeit vom Direct Line-Dienst an den Bot
- Verarbeitungszeit im Bot
- Übertragungszeit der Übermittlung der HTTP-Antwort zurück an den Client
Senden von Anlagen an den Bot
Manchmal muss ein Client Anlagen an den Bot senden, z. B. Bilder oder Dokumente. Ein Client kann Anlagen an den Bot entweder durch Angeben der URL(s) der Anlage(n) in dem mithilfe von POST /v3/directline/conversations/{conversationId}/activities gesendeten Aktivität-Objekt oder durch Hochladen der Anlage(n) mit POST /v3/directline/conversations/{conversationId}/upload senden.
Senden von Anlagen mittels URL
Um einen oder mehrere Anlagen als Teil des Aktivität-Objekts mit POST /v3/directline/conversations/{conversationId}/activities zu senden, fügen Sie ein oder mehrere Anlage-Objekte in das Activity-Objekt ein, und legen Sie die contentUrl-Eigenschaft jedes Attachment-Objekts auf den HTTP-, HTTPS- oder data-URI der Anlage fest.
Senden von Anlagen mittels Upload
Häufig möchte ein Client auf einem Gerät gespeicherte Bilder oder Dokumente an den Bot senden, aber es gibt keine URLs für diese Dateien. In diesem Fall kann ein Client eine POST /v3/directline/conversations/{conversationId}/upload-Anforderung zum Senden von Anlagen an den Bot per Upload ausgeben. Format und Inhalt der Anforderung richtet sich danach, ob der Client eine einzelne Anlage oder mehrere Anlagen sendet.
Senden einer einzelnen Anlage per Upload
Wenn Sie eine einzelne Anlage per Upload senden möchten, geben Sie diese Anforderung aus:
POST https://directline.botframework.com/v3/directline/conversations/{conversationId}/upload?userId={userId}
Authorization: Bearer SECRET_OR_TOKEN
Content-Type: TYPE_OF_ATTACHMENT
Content-Disposition: ATTACHMENT_INFO
[other headers]
[file content]
Ersetzen Sie in diesem Anforderungs-URI {conversationId} durch die ID der Konversation und {userId} durch die ID des Benutzers, der die Nachricht sendet. Der userId-Parameter ist erforderlich. Legen Sie in den Anforderungsheadern Content-Type auf den Typ der Anlage und Content-Disposition auf den Dateinamen der Anlage fest.
Die folgenden Codeausschnitte enthalten ein Beispiel für die Send (single) Attachment-Anforderung und -Antwort.
Anforderung
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: image/jpeg
Content-Disposition: name="file"; filename="badjokeeel.jpg"
[other headers]
[JPEG content]
Antwort
Ist die Anforderung erfolgreich, wird eine message-Aktivität an den Bot gesendet, wenn der Upload abgeschlossen ist, und die Antwort, die der Client empfängt, enthält die ID der gesendeten Aktivität.
HTTP/1.1 200 OK
[other headers]
{
"id": "0003"
}
Senden mehrerer Anlagen durch Upload
Um mehrere Anlagen per Upload zu senden, senden Sie eine mehrteilige POST-Anforderung an den /v3/directline/conversations/{conversationId}/upload-Endpunkt. Legen Sie den Content-Type-Header der Anforderung auf multipart/form-data fest, und fügen Sie den Content-Type-Header und den Content-Disposition-Header für die einzelnen Teile hinzu, um Typ und Dateinamen der Anlage anzugeben. Legen Sie den userId-Parameter im Anforderungs-URI auf die ID des Benutzers fest, der die Nachricht sendet.
Sie können ein Activity-Objekt in die Anforderung einfügen, indem Sie einen Teil hinzufügen, der den Content-Type-Headerwert application/vnd.microsoft.activity angibt. Wenn die Anforderung eine Aktivität enthält, werden die Anlagen, die von anderen Teilen der Nutzlast angegeben werden, als Anlagen zu dieser Aktivität hinzugefügt, bevor sie gesendet wird. Wenn die Anforderung keine Aktivität enthält, wird eine leere Aktivität erstellt, um als Container zu dienen, in dem die angegebenen Anlagen gesendet werden.
Die folgenden Codeausschnitte enthalten ein Beispiel für die Send (multiple) Attachments-Anforderung und -Antwort. In diesem Beispiel sendet die Anforderung eine Nachricht, die Text und ein einzelnes Bild als Anlage enthält. Um der Nachricht mehrere Anlagen hinzuzufügen, können zusätzliche Teile zur Anforderung hinzugefügt werden.
Anforderung
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: multipart/form-data; boundary=----DD4E5147-E865-4652-B662-F223701A8A89
[other headers]
----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: image/jpeg
Content-Disposition: form-data; name="file"; filename="badjokeeel.jpg"
[other headers]
[JPEG content]
----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: application/vnd.microsoft.activity
[other headers]
{
"type": "message",
"from": {
"id": "user1"
},
"text": "Hey I just IM'd you\n\nand this is crazy\n\nbut here's my webhook\n\nso POST me maybe"
}
----DD4E5147-E865-4652-B662-F223701A8A89
Antwort
Ist die Anforderung erfolgreich, wird eine „message“-Aktivität an den Bot gesendet, wenn der Upload abgeschlossen ist, und die Antwort, die der Client empfängt, enthält die ID der gesendeten Aktivität.
HTTP/1.1 200 OK
[other headers]
{
"id": "0004"
}