Уведомления о входящем звонке: технические сведенияIncoming call notifications: technical details

В процессе регистрации абонента и приглашения на собрание для Microsoft Teamsмы упомянули URL-адрес веб-перехватчика (для вызова) — конечная точка веб-перехватчика для всех входящих вызовов в Bot.In Registering a calling and meeting bot for Microsoft Teams, we mentioned the Webhook (for calling) URL — the webhook endpoint for all incoming calls to your bot. В этом разделе обсуждаются технические сведения, которые необходимо ответить на эти уведомления.This topic discusses the technical details you'll need to respond to these notifications.

Определение протоколаProtocol determination

Входящее уведомление предоставляется в устаревшем формате для совместимости с предыдущим протоколом Skype.The incoming notification is provided in legacy format for compatibility with the previous Skype protocol. Чтобы преобразовать вызов в протокол Microsoft Graph, ваш Bot должен определить, находится ли уведомление в устаревшем формате и ответить:In order to convert the call to the Microsoft Graph protocol, your bot must determine whether the notification is in legacy format and reply with:

HTTP/1.1 204 No Content

Ваш робот снова получит уведомление, но на этот раз в протоколе Microsoft Graph.Your bot will receive the notification again, but this time in the Microsoft Graph protocol.

В будущих выпусках мультимедийной платформы реального времени мы разберем, как настроить протокол, поддерживаемый приложением, чтобы избежать получения исходного обратного вызова в устаревшем формате.In a future release of the Real-time Media Platform, we'll allow you to configure the protocol your application supports to avoid receiving the initial callback in the legacy format.

Перенаправление для сходства регионаRedirects for region affinity

Вы назовите свой веб-перехватчик из центра обработки данных, в котором размещен вызов.You'll call your webhook from the data-center hosting the call. Вызов может начаться в любом центре обработки данных и не потребует сходства с областями счетов.The call may start in any data center and doesn't take into account region affinities. Уведомление будет отправлено в развертывание в зависимости от разрешения GeoDNS.The notification will be sent to your deployment depending on the GeoDNS resolution. Если приложение определяет, изменив полезные полезные данные уведомления или иным образом, оно должно выполняться в другом развертывании, приложение может ответить следующим образом:If your application determines, by inspecting the initial notification payload or otherwise, that it needs to run in a different deployment, the application may reply with:

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

Разрешить интерфейсу Bot отвечать на входящий вызов с помощью API ответов .Enable your bot to answer an incoming call using the answer API. Вы можете задать callbackUri обработку этого конкретного вызова.You can specify the callbackUri to handle this particular call. Это полезно для экземпляров с ведением состояния , где вызов обрабатывается определенным разделом и необходимо внедрить эту информацию в маршрут callbackUri для маршрутизации в нужный экземпляр.This is useful for stateful instances where your call is handled by a particular partition and you want to embed this information in the callbackUri for routing to the right instance.

Проверка подлинности обратного вызоваAuthenticating the callback

Ваш робот должен проверить маркер, отправленный на веб-перехватчик, чтобы проверить запрос.Your bot should inspect the token posted to your webhook to validate the request. Когда API отправляется в веб-перехватчик, сообщение POST HTTP содержит маркер OAuth в заголовке авторизации в качестве маркера носителя с аудиторией в качестве идентификатора приложения.Whenever the API posts to the webhook, the HTTP POST message contains an OAuth token in the Authorization header as a Bearer token, with audience as your application's App ID.

Приложение должно проверить этот маркер, прежде чем принимать запрос обратного вызова.Your application should validate this token before accepting the callback request.

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.The OAuth token will have values like the following, and will be signed by Skype. Конфигурацию OpenID, опубликованную https://api.aps.skype.com/v1/.well-known/OpenIdConfiguration в, можно использовать для проверки маркера.The OpenID configuration published at https://api.aps.skype.com/v1/.well-known/OpenIdConfiguration can be used to verify the token.

{
    "aud": "0efc74f7-41c3-47a4-8775-7259bfef4241",
    "iss": "https://api.botframework.com",
    "iat": 1466741440,
    "nbf": 1466741440,
    "exp": 1466745340,
    "tid": "1fdd12d0-4620-44ed-baec-459b611f84b2"
}
  • ауд аудитория — это URI идентификатора приложения, указанный для приложения.aud audience is the App ID URI specified for the application.
  • tid — идентификатор клиента для contoso.com.tid is the tenant id for Contoso.com.
  • ISS — это поставщик маркеров, https://api.botframework.com.iss is the token issuer, https://api.botframework.com.

При обработке кода веб-перехватчику необходимо проверить маркер, убедиться, что срок его действия истек, и проверить, подписан ли он опубликованной конфигурацией OpenID.Your code handling the webhook should validate the token, ensure it hasn't expired, and check whether it has been signed by our published OpenID configuration. Кроме того, необходимо проверить, соответствует ли ауд идентификатору приложения, прежде чем принимать запрос обратного вызова.You should also check whether aud matches your App ID before accepting the callback request.

В примере показано, как проверить входящие запросы.Sample shows how to validate inbound requests.