开通消息通知服务

概述

Agora 提供消息通知服务，用于实时同步实时音视频业务中的频道状态。

开通消息通知服务后，当订阅的频道事件发生时，Agora 业务服务器会将事件消息发送给 Agora 消息通知服务器，然后 Agroa 消息通知服务器会通过 HTTPS POST 请求方法将事件通知投递给你的服务器。

工作原理图

前提条件

开通 Agora 消息通知服务前，请确保已经具备以下条件：

• 有效的 Agora 开发者账号。如果你还没有注册 Agora 开发者账号，参考注册与登录。
• 启用中的 Agora 控制台项目。如果你还没有创建过项目，参考创建和管理项目。
• 网络访问。如果你的网络环境部署了防火墙，请调用 IP 地址查询 API 获取 Agora 消息通知服务器的 IP 地址并添加到防火墙白名单，以正常使用 Agora 消息通知服务。

开通服务

按照以下步骤，在 Agora 控制台开通消息通知服务：

1. 登录 Agora 控制台，点击左侧导航栏的项目管理。

2. 在项目管理页面，选择需要开通消息通知服务的项目，点击配置。
   

3. 在实时互动拓展能力下，找到消息通知服务，点击配置。
   

4. 在消息通知服务配置页面，填入下列信息并点击保存：

   • 产品名称：RTC 频道事件回调。
   • Event：需要订阅的频道事件。详见实时音视频频道事件类型。
     如需配置 QPS (Query Per Second) 较高的事件，如实时音视频中观众加入或离开直播频道，请确保你的服务器有足够的处理能力。
     建议一次选择所有需要订阅的事件，以避免多次配置和审核。
   • 接收服务器所在地：你的消息通知接收服务器所在的区域。Agora 会根据你提供的区域就近接入 Agora 节点服务器。
   • 接收服务器 URL：接收消息通知的 HTTPS 服务器地址。
     • 为提高安全性，Agora 消息通知服务不再支持 HTTP 服务器地址。
     • 为降低消息投递延时，Agora 建议你的服务器支持 HTTPS 连接重用，即 keep-alive 模式，并进行如下设置：
       • MaxKeepAliveRequests：大于等于 100。
       • KeepAliveTimeout：大于等于 10 秒。
   • 密钥：用于验证签名的密钥（secret）。关于如何使用密钥验证签名，详见验证签名。
   • IP 白名单：如果你的消息接收服务器受防火墙限制，请勾选该选项，调用 API 查询 Agora 消息通知服务器的 IP 地址 并将获取的所有 IP 地址都添加到防火墙白名单。

5. 点击保存后，Agora 会对你的配置进行健康检查，步骤如下：

   a. 根据你订阅的事件生成对应的测试事件，并向你的服务器发送事件回调。在测试事件回调中，channelName 为 test_webhook，uid 为 12121212。
   b. 接收到每个测试事件回调后，你的服务器需要在 10 秒内对 Agora 消息服务器作出响应，响应状态码必须为 200，响应包体格式为 JSON，包体内容不作要求。

   健康检查成功后，点击保存 NCS 配置。

   

   如果健康检查失败，请根据 Agora 控制台的提示进行错误排查。常见的错误包括：

   • 请求超时：你的服务器没有在 10 秒内返回 200。请检查你的服务器是否及时对事件回调作出正确的响应。如果响应正确，请联系技术支持确认 Agora 消息通知服务器到你的服务器之间的网络连接是否正常。
   • 证书错误：HTTPS 证书错误。请检查证书是否正确。如果你的服务器受防火墙限制，请检查是否已将 Agora 消息通知服务器的 IP 地址全部添加到防火墙白名单。
   • 域名不可达：域名不合法，无法解析到目标 IP 地址。请检查你的服务器部署是否正确。
   • 响应错误：你的服务器返回的响应状态码不为 200，具体的状态码和描述详见控制台提示。

6. 阅读弹出提示，点击保存 NCS 配置。
   
   配置通过审核后，消息通知服务的状态会显示已启用。

消息通知回调格式与内容

成功开通 Agora 消息通知服务后，当订阅的频道事件发生时，Agora 消息服务器会以 HTTPS POST 请求的形式向你的服务器发送消息通知回调。详见实时音视频频道事件类型。

消息通知回调响应

接收到消息通知回调后，你的服务器需要在 10 秒内对 Agora 消息服务器作出响应。响应包体格式为 JSON，包体内容不作要求。

Agora 消息服务器发送通知后的 10 秒内，如果没有收到你的服务器的响应或响应状态码不是 200，会认为消息通知失败。失败后，Agora 消息通知服务器会立即重新发送消息通知，投递间隔随着重试次数的上升逐渐增加，直到重试三次后停止投递。

查询消息通知服务器的 IP 地址

如果你的消息接收服务器受防火墙限制，你需要调用 RESTful API 查询 Agora 消息通知服务器的 IP 地址并将获取到的所有 IP 地址都添加到防火墙白名单。

Agora 可能会调整消息通知服务器的 IP 地址。因此，强烈推荐你至少每 24 小时进行一次查询，并自动更新防火墙配置，否则可能会影响你接收通知。

接口原型

• 方法：GET
• 接入点：https://api.agora.io/v2/ncs/ip

请求头部

Authorization：你需要使用 Agora 提供的客户 ID和客户密钥，以及 Base64 算法生成一个凭证，并填入 HTTP 请求头部的 Authorization 字段。详见实现 HTTP 基本认证。

请求包体

该 API 无包体参数。

响应包体

请求成功时，响应包体的示例如下：

{
    "data": {
        "service": {
            "hosts": [
                {
                    "primaryIP": "xxx.xxx.xxx.xxx"
                },
                {
                    "primaryIP": "xxx.xxx.xxx.xxx"
                }
            ]
        }
    }
}

字段含义：

primaryIP：Agora 消息通知服务器的 IP 地址。收到响应时，你仅需关心该字段，并将 IP 地址（或 IP 地址列表）添加到白名单中。

注意事项

• Agora 消息通知服务不保证消息通知完全按照事件发生的顺序到达，你的服务器需要能处理乱序消息。
• 为提高消息服务的可靠性，每次事件可能会有不止一次消息通知，你的服务器需要能处理重复消息。