Erstellen eines Bots mit dem bot-Connector-Dienst und der bot-Connector-APICreate a bot with the Bot Connector service with the Bot Connector API

Der Bot Connector-Dienst ermöglicht es Ihrem Bot, Nachrichten mit im Azure-Portal konfigurierten Kanälen auszutauschen. Hierzu werden die Branchenstandards REST und JSON über HTTPS verwendet.The Bot Connector service enables your bot to exchange messages with channels that are configured in the Azure Portal, by using industry-standard REST and JSON over HTTPS. 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.This tutorial walks you through the process of obtaining an access token from the Bot Framework and using the Bot Connector service to exchange messages with the user.

Abrufen eines ZugriffstokensGet an access token

Wichtig

Falls nicht bereits geschehen, müssen Sie Ihren Bot bei Bot Framework registrieren, um dessen App-ID und Kennwort zu erhalten.If you have not already done so, you must register your bot with the Bot Framework to obtain its App ID and password. Sie benötigen die App-ID und das Kennwort des Bots, um ein Zugriffstoken abzurufen.You will need the bot's AppID and password to get an access token.

Um mit dem Bot Connector-Dienst zu kommunizieren, müssen Sie ein Zugriffstoken im Authorization-Header jeder API-Anforderung unter Verwendung dieses Formats angeben:To communicate with the Bot Connector service, you must specify an access token in the Authorization header of each API request, using this format:

Authorization: Bearer ACCESS_TOKEN

Sie können das Zugriffstoken für Ihren Bot abrufen, indem Sie eine API-Anforderung senden.You can obtain the access token for your bot by issuing an API request.

AnforderungRequest

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.To request an access token that can be used to authenticate requests to the Bot Connector service, issue the following request, replacing MICROSOFT-APP-ID and MICROSOFT-APP-PASSWORD with the App ID and password that you obtained when you registered your bot with the Bot Framework.

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

AntwortResponse

Wenn die Anforderung erfolgreich gesendet wird, erhalten Sie die Antwort „HTTP 200“, in der das Zugriffstoken und Informationen zu dessen Ablaufdatum angegeben werden.If the request succeeds, you will receive an HTTP 200 response that specifies the access token and information about its expiration.

{
    "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.For more details about authentication in the Bot Connector service, see Authentication.

Austauschen von Nachrichten mit dem BenutzerExchange messages with the user

Bei einer Konversation handelt es sich um einen Austausch mehrerer Nachrichten zwischen einem Benutzer und Ihrem Bot.A conversation is a series of messages exchanged between a user and your bot.

Empfangen einer Nachricht vom BenutzerReceive a message from the user

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.When the user sends a message, the Bot Framework Connector POSTs a request to the endpoint that you specified when you registered your bot. Bei dem Anforderungstext handelt es sich um ein Aktivität-Objekt.The body of the request is an Activity object. Das folgende Beispiel zeigt den Anforderungstext, den der Bot empfängt, wenn der Benutzer eine einfache Nachricht an den Bot sendet.The following example shows the request body that a bot receives when the user sends a simple message to the bot.

{
    "type": "message",
    "id": "bf3cc9a2f5de...",
    "timestamp": "2016-10-19T20:17:52.2891902Z",
    "serviceUrl": "https://smba.trafficmanager.net/apis",
    "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 BenutzersReply to the user's message

Wenn der Botendpunkt eine POST-Anforderung empfängt, die eine Nachricht des Benutzers darstellt (d. h. type = Nachricht), verwenden Sie die Informationen in dieser Anforderung, um das Aktivität-Objekt für Ihre Antwort zu erstellen.When your bot's endpoint receives a POST request that represents a message from the user (i.e., type = message), use the information in that request to create the Activity object for your response.

  1. Legen Sie die conversation-Eigenschaft auf die Inhalte der conversation-Eigenschaft in der Nachricht des Benutzers fest.Set the conversation property to the contents of the conversation property in the user's message.
  2. Legen Sie die from-Eigenschaft auf die Inhalte der recipient-Eigenschaft in der Nachricht des Benutzers fest.Set the from property to the contents of the recipient property in the user's message.
  3. Legen Sie die recipient-Eigenschaft auf die Inhalte der from-Eigenschaft in der Nachricht des Benutzers fest.Set the recipient property to the contents of the from property in the user's message.
  4. Legen Sie die Eigenschaften text und attachments nach Bedarf fest.Set the text and attachments properties as appropriate.

Verwenden Sie die serviceUrl-Eigenschaft in der eingehenden Anforderung zum Identifizieren des Basis-URI, über den Ihr Bot die Antwort ausgeben sollte.Use the serviceUrl property in the incoming request to identify the base URI that your bot should use to issue its response.

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.To send the response, POST your Activity object to /v3/conversations/{conversationId}/activities/{activityId}, as shown in the following example. Bei dem Anforderungstext handelt es sich um ein Activity-Objekt, das den Benutzer dazu auffordert, einen verfügbaren Termin auszuwählen.The body of this request is an Activity object that prompts the user to select an available appointment time.

POST https://smba.trafficmanager.net/apis/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/apis den Basis-URI dar. Der Basis-URI für Anforderungen, die Ihr Bot ausgibt, kann ein anderer sein.In this example request, https://smba.trafficmanager.net/apis represents the base URI; the base URI for requests that your bot issues may be different. Weitere Informationen zum Festlegen des Basis-URI finden Sie in der API-Referenz.For details about setting the base URI, see API Reference.

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.As shown in this example, the Authorization header of each API request that you send must contain the word Bearer followed by the access token that you obtained from the Bot Framework.

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:To send another message that enables a user to select an available appointment time by clicking a button, POST another request to the same endpoint:

POST https://smba.trafficmanager.net/apis/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 SchritteNext steps

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.In this tutorial, you obtained an access token from the Bot Framework and used the Bot Connector service to exchange messages with the user. Sie können den Bot Framework-Emulator zum Testen und Debuggen Ihres Bots verwenden.You can use the Bot Framework Emulator to test and debug your bot. Wenn Sie Ihren Bot für andere freigeben möchten, müssen Sie diesen für die Ausführung auf mindestens einem Kanal konfigurieren.If you'd like to share your bot with others, you'll need to configure it to run on one or more channels.