Agora 提供消息通知服务,用于实时同步实时音视频业务中的频道状态。
开通消息通知服务后,当订阅的频道事件发生时,Agora 业务服务器会将事件消息发送给 Agora 消息通知服务器,然后 Agroa 消息通知服务器会通过 HTTPS POST 请求方法将事件通知投递给你的服务器。
开通 Agora 消息通知服务前,请确保已经具备以下条件:
按照以下步骤,在 Agora 控制台开通消息通知服务:
登录 Agora 控制台,点击左侧导航栏的项目管理。
在项目管理页面,选择需要开通消息通知服务的项目,点击配置。
在实时互动拓展能力下,找到消息通知服务,点击配置。
在消息通知服务配置页面,填入下列信息并点击保存:
MaxKeepAliveRequests
:大于等于 100。KeepAliveTimeout
:大于等于 10 秒。点击保存后,Agora 会对你的配置进行健康检查,步骤如下:
a. 根据你订阅的事件生成对应的测试事件,并向你的服务器发送事件回调。在测试事件回调中,channelName
为 test_webhook
,uid
为 12121212
。
b. 接收到每个测试事件回调后,你的服务器需要在 10 秒内对 Agora 消息服务器作出响应,响应状态码必须为 200,响应包体格式为 JSON,包体内容不作要求。
健康检查成功后,点击保存 NCS 配置。
如果健康检查失败,请根据 Agora 控制台的提示进行错误排查。常见的错误包括:
阅读弹出提示,点击保存 NCS 配置。
配置通过审核后,消息通知服务的状态会显示已启用。
成功开通 Agora 消息通知服务后,当订阅的频道事件发生时,Agora 消息服务器会以 HTTPS POST 请求的形式向你的服务器发送消息通知回调。详见实时音视频频道事件类型。
接收到消息通知回调后,你的服务器需要在 10 秒内对 Agora 消息服务器作出响应。响应包体格式为 JSON,包体内容不作要求。
Agora 消息服务器发送通知后的 10 秒内,如果没有收到你的服务器的响应或响应状态码不是 200,会认为消息通知失败。失败后,Agora 消息通知服务器会立即重新发送消息通知,投递间隔随着重试次数的上升逐渐增加,直到重试三次后停止投递。
如果你的消息接收服务器受防火墙限制,你需要调用 RESTful API 查询 Agora 消息通知服务器的 IP 地址并将获取到的所有 IP 地址都添加到防火墙白名单。
Agora 可能会调整消息通知服务器的 IP 地址。因此,强烈推荐你至少每 24 小时进行一次查询,并自动更新防火墙配置,否则可能会影响你接收通知。
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 地址列表)添加到白名单中。