Erstellen eines Bots mit dem Bot Connector-Dienst mit der Bot Connector-API

Artikel
03/08/2023

Mit dem Bot Connector-Dienst kann Ihr Bot Nachrichten mit Kanälen austauschen, die im Azure-Portal konfiguriert sind, indem er REST und JSON nach Branchenstandard über HTTPS verwendet. In diesem Tutorial erhalten Sie Anweisungen zum Abrufen eines Zugriffstokens aus Bot Framework und zum Verwenden des Bot Connector-Dienst zum Austauschen von Nachrichten zwischen Benutzern.

Abrufen eines Zugriffstokens

Wichtig

Wenn Sie dies noch nicht getan haben, müssen Sie Ihren Bot beim Bot Framework registrieren, um die App-ID und das Kennwort zu erhalten. Sie benötigen die App-ID und das Kennwort des Bots, um ein Zugriffstoken abzurufen.

Um mit dem Bot Connector-Dienst zu kommunizieren, müssen Sie ein Zugriffstoken im Authorization-Header jeder API-Anforderung unter Verwendung dieses Formats angeben:

Authorization: Bearer ACCESS_TOKEN

Sie können das Zugriffstoken für Ihren Bot abrufen, indem Sie eine API-Anforderung senden.

Anforderung

Führen Sie die folgende Anforderung aus, um ein Zugriffstoken anzufordern, dass zum Authentifizieren von Anforderungen an den Bot Connector-Dienst verwendet werden kann. Ersetzen Sie dabei MICROSOFT-APP-ID und MICROSOFT-APP-PASSWORD durch die App-ID und das Kennwort, das Sie bei der Registrierung Ihres Bots bei Bot Framework erhalten haben.

POST https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=MICROSOFT-APP-ID&client_secret=MICROSOFT-APP-PASSWORD&scope=https%3A%2F%2Fapi.botframework.com%2F.default

Antwort

Wenn die Anforderung erfolgreich ist, erhalten Sie eine HTTP 200-Antwort, die das Zugriffstoken und Informationen zu dessen Ablauf angibt.

{
    "token_type":"Bearer",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJhbGciOiJIUzI1Ni..."
}

Tipp

Weitere Informationen zur Authentifizierung im Bot Connector-Dienst finden Sie unter Authentifizierung.

Austauschen von Nachrichten mit dem Benutzer

Bei einer Konversation handelt es sich um einen Austausch mehrerer Nachrichten zwischen einem Benutzer und Ihrem Bot.

Empfangen einer Nachricht vom Benutzer

Wenn der Benutzer eine Nachricht sendet, sendet der Bot Framework Connector eine Anforderung an den Endpunkt, den Sie bei der Registrierung Ihres Bots angegeben haben. Bei dem Anforderungstext handelt es sich um ein Aktivität-Objekt. Das folgende Beispiel zeigt den Anforderungstext, den der Bot empfängt, wenn der Benutzer eine einfache Nachricht an den Bot sendet.

{
    "type": "message",
    "id": "bf3cc9a2f5de...",
    "timestamp": "2016-10-19T20:17:52.2891902Z",
    "serviceUrl": "https://smba.trafficmanager.net/teams",
    "channelId": "channel's name/id",
    "from": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
    "recipient": {
        "id": "12345678",
        "name": "bot's name"
    },
    "text": "Haircut on Saturday"
}

Antworten auf die Nachricht des Benutzers

Wenn der Endpunkt Ihres Bots eine POST Anforderung empfängt, die eine Nachricht vom Benutzer darstellt (z. B. eine Nachricht), verwenden Sie die Informationen in dieser Anforderung, type = um das Activity-Objekt für Ihre Antwort zu erstellen.

Legen Sie die conversation-Eigenschaft auf die Inhalte der conversation-Eigenschaft in der Nachricht des Benutzers fest.
Legen Sie die from-Eigenschaft auf die Inhalte der recipient-Eigenschaft in der Nachricht des Benutzers fest.
Legen Sie die recipient-Eigenschaft auf die Inhalte der from-Eigenschaft in der Nachricht des Benutzers fest.
Legen Sie die Eigenschaften text und attachments nach Bedarf fest.

Verwenden Sie die serviceUrl-Eigenschaft in der eingehenden Anforderung zum Identifizieren des Basis-URI, über den Ihr Bot die Antwort ausgeben sollte.

Führen Sie zum Senden der Antwort einen POST-Vorgang für Ihr Activity-Objekt an /v3/conversations/{conversationId}/activities/{activityId} durch, wie im folgenden Beispiel zu sehen. Bei dem Anforderungstext handelt es sich um ein Activity-Objekt, das den Benutzer dazu auffordert, einen verfügbaren Termin auszuwählen. Weitere Informationen zum Festlegen des Basis-URI finden Sie in der API-Referenz.

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/bf3cc9a2f5de... 
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "bot's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "text": "I have these times available:",
    "replyToId": "bf3cc9a2f5de..."
}

In dieser Beispielanforderung stellt https://smba.trafficmanager.net/teams den Basis-URI dar. Der Basis-URI für Anforderungen, die Ihr Bot ausgibt, kann ein anderer sein. Weitere Informationen zum Festlegen des Basis-URI finden Sie in der API-Referenz.

Wichtig

Wie in diesem Beispiel gezeigt, muss der Authorization-Header jeder von Ihnen gesendeten API-Anforderung das Wort Bearer enthalten. Darauf muss das Zugriffstoken folgen, das Sie von Bot Framework erhalten haben.

Senden (POST) Sie eine weitere Anforderung an denselben Endpunkt, um eine andere Nachricht zu senden, über die der Benutzer mithilfe eines Klicks auf eine Schaltfläche einen verfügbaren Termin auswählen kann:

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/bf3cc9a2f5de... 
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "bot's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "attachmentLayout": "list",
    "attachments": [
      {
        "contentType": "application/vnd.microsoft.card.thumbnail",
        "content": {
          "buttons": [
            {
              "type": "imBack",
              "title": "10:30",
              "value": "10:30"
            },
            {
              "type": "imBack",
              "title": "11:30",
              "value": "11:30"
            },
            {
              "type": "openUrl",
              "title": "See more",
              "value": "http://www.contososalon.com/scheduling"
            }
          ]
        }
      }
    ],
    "replyToId": "bf3cc9a2f5de..."
}

Nächste Schritte

In diesem Tutorial wurde erläutert, wie Sie ein Zugriffstoken von Bot Framework erhalten und den Bot Connector-Dienst zum Austauschen von Nachrichten zwischen Benutzern verwenden können. Sie können den Bot Framework-Emulator zum Testen und Debuggen Ihres Bots verwenden. Wenn Sie Ihren Bot für andere freigeben möchten, müssen Sie diesen für die Ausführung auf mindestens einem Kanal konfigurieren.