Bot Connector API を使用して Bot Connector サービスを使用してボットを作成する

[アーティクル]
10/07/2023

Bot Connector サービスを使用すると、ボットは HTTPS 経由で業界標準の REST と JSON を使用して、Azure portalで構成されたチャネルとメッセージを交換できます。このチュートリアルでは、Bot Framework からアクセストークンを取得し、Bot Connector サービスを使用してユーザーとメッセージを交換する手順について説明します。

アクセストークンを取得する

重要

まだ行っていない場合は、Bot Framework にボットを登録して、アプリ ID とパスワードを取得する必要があります。アクセストークンを取得するには、ボットの AppID とパスワードが必要です。

Bot Connector サービスと通信するには、次の形式を使用して、各 API 要求の Authorization ヘッダーでアクセストークンを指定する必要があります。

Authorization: Bearer ACCESS_TOKEN

お使いのボット用のアクセストークンを取得するには、API 要求を発行します。

Request

Bot Connector サービスに対する要求の認証に使用できるアクセストークンを要求するには、次を要求を発行します。MICROSOFT-APP-ID および MICROSOFT-APP-PASSWORD は、ご自身のボットを Bot Framework に登録したときに取得したアプリ ID とパスワードに置き換えてください。

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

Response

要求が成功すると、アクセストークンとその有効期限に関する情報を指定する HTTP 200 応答を受け取ります。

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

ヒント

Bot Connector サービスでの認証の詳細については、「Authentication (認証)」を参照してください。

ユーザーとメッセージを交換する

会話とは、ユーザーとご自身のボットの間で交換された一連のメッセージのことです。

ユーザーからメッセージを受信する

ユーザーがメッセージを送信すると、お使いのボットを登録したときに指定したエンドポイントに、Bot Framework Connector によって要求の POST が実行されます。要求の本文は Activity オブジェクトです。次の例は、ユーザーが簡単なメッセージをボットに送信したときに、ボット側で受信する要求本文を示しています。

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

ユーザーのメッセージに返信する

ボットのエンドポイントが、ユーザーからのメッセージ (メッセージなど) を表す要求を受け取POSTったら、type = その要求の情報を使用して、応答の Activity オブジェクトを作成します。

conversation プロパティを、ユーザーのメッセージの conversation プロパティのコンテンツに設定します。
from プロパティを、ユーザーのメッセージの recipient プロパティのコンテンツに設定します。
recipient プロパティを、ユーザーのメッセージの from プロパティのコンテンツに設定します。
必要に応じて、text プロパティと attachments プロパティを設定します。

着信要求の serviceUrl プロパティを使用して、その応答を発行するときに、ご自身のボットによって使用されるベース URI を特定します。

応答を送信するには、次の例に示すように、/v3/conversations/{conversationId}/activities/{activityId} に対して、ご自身の Activity オブジェクトの POST を実行します。この要求の本文は、ユーザーに使用可能な予定の時刻を選択するように求める Activity オブジェクトです。ベース URI の設定の詳細については、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..."
}

この要求の例で、https://smba.trafficmanager.net/teams はベース URI を示しています。ご利用のボットによって発行される要求に対するベース URI は、これとは異なる場合があります。ベース URI の設定の詳細については、API リファレンスに関する記事をご覧ください。

重要

この例で示すように、送信する各 API 要求の Authorization ヘッダーには、ベアラーというワードに続いて、Bot Framework から取得したアクセストークンが含まれている必要があります。

別のメッセージを送信して、使用可能な予定の時刻をユーザーがクリックによって選択できるようにするには、同じエンドポイントに対して他の要求の POST を実行します。

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

次のステップ

このチュートリアルでは、Bot Framework からアクセストークンを取得し、Bot Connector サービスを使用してユーザーとメッセージを交換しました。 Bot Framework エミュレーターを使用すると、お使いのボットのテストおよびデバッグを行うことができます。ご自身のボットを他のユーザーと共有したい場合は、そのボットが 1 つまたは複数のチャネルで実行されるように構成する必要があります。