Tworzenie bota za pomocą usługi Bot Connector przy użyciu interfejsu API łącznika botów

Artykuł
10/07/2023

Usługa Bot Connector umożliwia botowi wymianę komunikatów za pomocą kanałów skonfigurowanych w Azure Portal przy użyciu standardowego interfejsu REST i JSON za pośrednictwem protokołu HTTPS. Ten samouczek przeprowadzi Cię przez proces uzyskiwania tokenu dostępu z platformy Bot Framework i używania usługi Bot Connector do wymiany komunikatów z użytkownikiem.

Pobranie tokenu dostępu

Ważne

Jeśli jeszcze tego nie zrobiono, musisz zarejestrować bota w programie Bot Framework, aby uzyskać jego identyfikator aplikacji i hasło. Aby uzyskać token dostępu, musisz mieć identyfikator AppID i hasło bota.

Aby komunikować się z usługą Bot Connector, należy określić token dostępu w Authorization nagłówku każdego żądania interfejsu API przy użyciu następującego formatu:

Authorization: Bearer ACCESS_TOKEN

Token dostępu dla bota można uzyskać, wysyłając żądanie interfejsu API.

Żądanie

Aby zażądać tokenu dostępu, który może służyć do uwierzytelniania żądań w usłudze Bot Connector, wydaj następujące żądanie, zastępując ciąg MICROSOFT-APP-ID i MICROSOFT-APP-PASSWORD identyfikatorem aplikacji i hasłem uzyskanym podczas rejestrowania bota w usłudze 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

Reakcja

Jeśli żądanie zakończy się pomyślnie, otrzymasz odpowiedź HTTP 200, która określa token dostępu i informacje o jego wygaśnięciu.

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

Porada

Aby uzyskać więcej informacji na temat uwierzytelniania w usłudze Bot Connector, zobacz Uwierzytelnianie.

Wymiana komunikatów z użytkownikiem

Konwersacja to seria wiadomości wymienianych między użytkownikiem a botem.

Odbieranie komunikatu od użytkownika

Gdy użytkownik wyśle komunikat, łącznik Bot Framework Connector poSTs żądanie do punktu końcowego określonego podczas rejestrowania bota. Treść żądania jest obiektem Działania . W poniższym przykładzie pokazano treść żądania odbieraną przez bota, gdy użytkownik wysyła prosty komunikat do bota.

{
    "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"
}

Odpowiedz na wiadomość użytkownika

Gdy punkt końcowy bota odbiera POST żądanie reprezentujące komunikat od użytkownika (na przykład type = komunikat), użyj informacji w tym żądaniu, aby utworzyć obiekt Działania dla odpowiedzi.

Ustaw właściwość konwersacji na zawartość właściwości konwersacji w wiadomości użytkownika.
Ustaw właściwość from na zawartość właściwości adresata w komunikacie użytkownika.
Ustaw właściwość adresata na zawartość właściwości from w wiadomości użytkownika.
Ustaw odpowiednie właściwości tekstu i załączników .

serviceUrl Użyj właściwości w żądaniu przychodzącym, aby zidentyfikować podstawowy identyfikator URI, którego bot powinien użyć do wystawienia odpowiedzi.

Aby wysłać odpowiedź, POST obiekt Activity do /v3/conversations/{conversationId}/activities/{activityId}metody , jak pokazano w poniższym przykładzie. Treść tego żądania jest obiektem Activity , który monituje użytkownika o wybranie dostępnego terminu. Aby uzyskać szczegółowe informacje na temat ustawiania podstawowego identyfikatora URI, zobacz Dokumentacja interfejsu API.

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..."
}

W tym przykładowym żądaniu https://smba.trafficmanager.net/teams reprezentuje podstawowy identyfikator URI. Podstawowy identyfikator URI żądań, które mogą być inne. Aby uzyskać szczegółowe informacje na temat ustawiania podstawowego identyfikatora URI, zobacz Dokumentacja interfejsu API.

Ważne

Jak pokazano w tym przykładzie, Authorization nagłówek każdego wysyłanego żądania interfejsu API musi zawierać wyraz Bearer , a następnie token dostępu uzyskany z platformy Bot Framework.

Aby wysłać inny komunikat, który umożliwia użytkownikowi wybranie dostępnego terminu, klikając przycisk, POST kolejne żądanie do tego samego punktu końcowego:

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..."
}

Następne kroki

W tym samouczku uzyskaliśmy token dostępu z platformy Bot Framework i użyto usługi Bot Connector do wymiany komunikatów z użytkownikiem. Możesz użyć Bot Framework Emulator do testowania i debugowania bota. Jeśli chcesz udostępnić bota innym osobom, musisz skonfigurować go do uruchamiania w co najmniej jednym kanale.

Udostępnij za pośrednictwem