着信通知

  • [アーティクル]

Microsoft Teams の通話と会議ボットを登録する際には、URL を呼び出すための Webhook が記載されています。 この URL は、ボットへのすべての着信呼び出しの Webhook エンドポイントです。

プロトコルの決定

受信通知は、以前の Skype プロトコルとの互換性のためにレガシ形式で提供されます。 呼び出しを Microsoft Graph プロトコルに変換するには、ボットが通知がレガシ形式であるかどうかを判断し、次の応答を提供する必要があります。

HTTP/1.1 204 No Content

ボットはもう一度通知を受け取りますが、今回は Microsoft Graph プロトコルで受け取ります。

リアルタイム メディア プラットフォームの今後のリリースでは、アプリケーションでサポートされているプロトコルを構成して、レガシ形式の初期コールバックを受信しないようにすることができます。

次のセクションでは、デプロイへのリージョン アフィニティにリダイレクトされる着信呼び出し通知の詳細について説明します。

リージョン アフィニティのリダイレクト

通話をホストしているデータ センターから Webhook を呼び出します。 呼び出しはどのデータ センターでも開始され、リージョンアフィニティは考慮されません。 GeoDNS の解決に応じて、通知がデプロイに送信されます。 アプリケーションが、最初の通知ペイロードを検査するか、別のデプロイで実行する必要があると判断した場合、アプリケーションは次の応答を提供します。

HTTP/1.1 302 Found
Location: your-new-location

ボットが応答 API を使用して着信呼び出しに 応答 できるようにします。 を指定して、この特定の callbackUri 呼び出しを処理できます。 これは、呼び出しが特定のパーティションによって処理されるステートフル インスタンスで、 にこの情報 callbackUri を埋め込んで適切なインスタンスにルーティングする場合に便利です。

次のセクションでは、Webhook に投稿されたトークンを検査してコールバックを認証する方法について詳しく説明します。

コールバックを認証する

ボットは、Webhook に投稿されたトークンを検査して要求を検証する必要があります。 API が Webhook に投稿するたびに、HTTP POST メッセージには、承認ヘッダーにベアラー トークンとして OAuth トークンが含まれます。対象ユーザーはアプリケーションのアプリ ID です。

アプリケーションは、コールバック要求を受け入れる前に、このトークンを検証する必要があります。

コールバックを認証するには、次のサンプル コードを使用します。

POST https://bot.contoso.com/api/calls
Content-Type: application/json
Authentication: Bearer <TOKEN>

"value": [
    "subscriptionId": "2887CEE8344B47C291F1AF628599A93C",
    "subscriptionExpirationDateTime": "2016-11-20T18:23:45.9356913Z",
    "changeType": "updated",
    "resource": "/app/calls/8A934F51F25B4EE19613D4049491857B",
    "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "Established"
    }
]

OAuth トークンには次の値があり、Skype によって署名されています。

{
    "aud": "0efc74f7-41c3-47a4-8775-7259bfef4241",
    "iss": "https://api.botframework.com",
    "iat": 1466741440,
    "nbf": 1466741440,
    "exp": 1466745340,
    "tid": "1fdd12d0-4620-44ed-baec-459b611f84b2"
}

で https://api.aps.skype.com/v1/.well-known/OpenIdConfiguration 発行された OpenID 構成を使用して、トークンを確認できます。 各 OAuth トークン値は、次のように使用されます。

  • aud 対象ユーザーは、アプリケーションに対して指定されたアプリ ID URI です。
  • tid は、Contoso.com のテナント ID です。
  • iss はトークン発行者です https://api.botframework.com。。

コード処理のために、Webhook はトークンを検証し、期限切れになっていないことを確認し、発行された OpenID 構成によって署名されているかどうかをチェックする必要があります。 また、コールバック要求を受け入れる前に、aud がアプリ ID と一致するかどうかをチェックする必要があります。

詳細については、「 受信要求の検証」を参照してください。

次の手順

アプリケーションでホストされるメディア ボットの要件と考察

関連項目