你可以通过 RESTful API 创建云端播放器,将一路在线媒体流作为直播视频源输入到 Agora 频道内。输入成功后,该媒体流会在 Agora 频道内自动播放,供频道内的远端用户欣赏。
第一次使用输入在线媒体流,需要在 Agora 控制台开通服务,步骤如下:
开通成功后你可以在用量页面看到输入在线媒体流的使用情况。
Agora RESTful API 要求 Basic HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入 Authorization
字段。关于如何生成该字段的值,请参考 RESTful API 认证。
输入一路在线媒体流至 Agora 频道内播放相当于创建了一个云端播放器(cloud player)。用户可以通过 RESTful API 控制云端播放器,实现对该媒体流的控制:
Create
:在项目中创建一个云端播放器。
Delete
:在项目中销毁一个云端播放器。
List
:分页列出该项目中所有云端播放器。
使用 Number 型用户名(uid
)时,完整的 player
示例如下:
{
"name": "class32_101",
"streamUrl": "rtmp://example.agora.io/live/class32/101",
"channelName": "class32",
"uid": 101,
"token": "2a784467d6",
"idleTimeout": 300,
"playTs": 1575508644,
"id": "2a784467d647bb87b60b719f6fa56317",
"createTs": 1575508644,
"status": "running"
}
使用 String 型用户名(account
)时,完整的 player
示例如下:
如果使用 String 型
account
,请确保已经阅读如何使用 String 型用户名。
{
"name": "class33_teacher101",
"streamUrl": "rtmp://example.agora.io/live/class33/teacher101",
"channelName": "class33",
"account": "teacher101",
"token": "3b784467e7",
"idleTimeout": 300,
"playTs": 1575508655,
"id": "2a784467d647bb87b60b719f6fa56333",
"createTs": 1575508655,
"status": "running"
}
字段名 | 类型 | 用法 | 含义 |
---|---|---|---|
name |
String | 用户指定。 | 云端播放器的名字。 |
streamUrl |
String | 用户指定。 | 在线媒体流 URL 地址。 |
channelName |
String | 用户指定。 | Agora 频道名称。 |
uid |
Number | 云端播放器在 Agora 频道内的用户 UID。 | |
account |
String | 用户指定。 | 云端播放器在 Agora 频道内的用户 Account。 |
token |
String | 用户指定。 | 云端播放器在 Agora 频道内使用的动态密钥。 |
idleTimeout |
Number | 用户指定。 | 云端播放器处于空闲状态的最大时长(秒)。 |
playTs |
Number | 用户指定。 | 云端播放器开始播放在线媒体流时的 Unix 时间戳(秒)。 |
id |
String | Agora 服务器生成。 | 云端播放器的 ID。标识一个云端播放器。 |
createTs |
Number | Agora 服务器生成。 | 云端播放器创建时的 Unix 时间戳(秒)。 |
status |
String | Agora 服务器生成。 | 云端播放器的运行状态。 |
POST https://api.agora.io/{region}/v1/projects/{appId}/cloud-player/players
appId
:String 型必填参数。Agora 为每个开发者提供的 App ID。在 Agora 控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。region
: String 型必填参数。创建 Player
的区域。Agora 支持分区域创建 Player
,目前支持以下区域:cn
:中国大陆ap
:除中国大陆以外的亚洲区域na
:北美eu
:欧洲region
与你的媒体流源站在同一个区域。region
的值为小写。使用 Query Parameters 时的请求 URL 示例:
https://api.agora.io/{region}/v1/projects/{appId}/cloud-player/players?streamIp={streamIp}
streamIp
:String 型可选参数。媒体流源站 IP 地址。必须使用有效的 IPv4 地址。该参数可以保障媒体流的传输质量:
region
区域内的部分区域提供服务,请使用该参数。region
区域内的广泛的区域提供服务,请忽略该参数。Content-Type
: application/json
Authorization
:该字段的值需参考认证说明。
X-Request-ID
:UUID(通用唯一识别码),标识本次请求。传入该字段后,Agora 服务器会在响应 header 中返回该字段。
Agora 推荐用户对
X-Request-ID
赋值。如果用户不赋值,Agora 服务器会自动生成一个 UUID 传入。
使用 Number 型用户名(uid
)的示例:
{
"player": {
"streamUrl": "rtmp://example.agora.io/live/class32/101",
"channelName": "class32",
"token": "2a784467d6",
"uid": 101,
"idleTimeout": 300,
"playTs": 1575508644,
"name": "test"
}
}
使用 String 型用户名(account
)的示例:
{
"player": {
"streamUrl": "rtmp://example.agora.io/live/class32/101",
"channelName": "class32",
"token": "2a784467d6",
"account": "teacher101",
"idleTimeout": 300,
"playTs": 1575508644,
"name": "test"
}
}
请求 Body 为 JSON Object 类型的 player
字段,包含如下字段:
- 用户必须设置云端播放器在 Agora 频道内的用户名,它可以为 Number 型的
uid
或 String 型的account
。如果不设置用户名,该云端播放器不能创建,Agora 服务器会返回400(Bad Request)
的状态码。如果使用 String 型account
,请确保已经阅读如何使用 String 型用户名。- 为确保请求成功,请不要将必填字段设为
null
或""
。
streamUrl
:String 型必填字段。在线媒体流 URL 地址。必须为有效的 HTTP/HTTPS/RTMP/HLS 地址,且长度在 1024 个字符以内。
channelName
:String 型必填字段。Agora 频道名称。字符串长度必须在 64 字节以内,支持以下字符集(共 89 个字符):
uid
:Number 型可选字段。云端播放器在 Agora 频道内的用户 UID。取值范围为 0 到(232-1)。取值 0 时,Agora 服务器自动为 player 分配一个 UID。
请确保该值与频道内其他用户、云端播放器的 UID 都不同,否则影响播放质量。
account
:String 型可选字段。云端播放器在 Agora 频道内的用户 Account。该字段不能超过 255 字节,也不能为空字符串。支持的字符集范围(共 89 个字符)如下:
所有小写英文字母(a-z)
所有大写英文字母(A-Z)
数字 0-9
空格
"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
请确保该值与频道内其他用户、云端播放器的 Account 都不同,否则影响播放质量。
token
:String 型可选字段。云端播放器在 Agora 频道内使用的动态密钥。如在 Agora 控制台未启用 App 证书,则不需要向 token
传值;如在 Agora 控制台已启用 App 证书,则必须传入 token
:
idleTimeout
:Number 型可选字段。云端播放器处于空闲状态的最大时长(秒),即媒体流为非播放状态的最大时长。空闲状态超过设置的 idleTimeout
后,该播放器会自动销毁。取值范围为 5 到 600。默认值为 300。如果取值小于 5,Agora 服务器会自动调整为 5;如果取值大于 600,Agora 服务器会自动调整为 600。
playTs
:Number 型可选字段。云端播放器开始播放在线媒体流时的 Unix 时间戳(秒)。假设云端播放器创建时的 Unix 时间戳是 T,playTs
的取值范围为 [T - 86400,T + 300]。默认值为 0,代表云端播放器在创建成功时自动播放在线媒体流。假设 playTs
取值为 S:
playTs
字段设为云端播放器 A 开始播放在线媒体流时的 Unix 时间戳。name
:String 型可选参数。云端播放器的名字。长度必须在 64 个字符以内,支持的字符集范围为:
所有小写英文字母(a-z)
所有大写英文字母(A-Z)
数字 0-9
"-", "_"
name
为空。同一时间,一个项目下可以有多个 name
为空的云端播放器。同一时间,一个项目下不允许出现重名的云端播放器,用户尝试创建同名的云端播放器时会收到响应状态码 409(Conflict)
。 encryptMode
:String 型可选参数。内置加密模式。Agora 推荐使用 aes-128-gcm2
或 aes-256-gcm2
加密模式。这两种模式支持使用盐,安全性更高。
aes-128-xts
:128 位 AES 加密,XTS 模式。aes-256-xts
:256 位 AES 加密,XTS 模式。aes-128-ecb
:128 位 AES 加密,ECB 模式。sm4-128-ecb
:128 位 SM4 加密,ECB 模式。aes-128-gcm
:128 位 AES 加密,GCM 模式。aes-256-gcm
:256 位 AES 加密,GCM 模式。aes-128-gcm2
:128 位 AES 加密,GCM 模式。 相比于 aes-128-gcm
加密模式,aes-128-gcm2
加密模式安全性更高且需要设置盐(encryptKdfSalt
)。aes-256-gcm2
:256 位 AES 加密,GCM 模式。相比于 aes-256-gcm
加密模式,aes-256-gcm2
加密模式安全性更高且需要设置盐(encryptKdfSalt
)。encryptKey
:String 型可选参数。内置加密密钥,字符串类型,长度无限制。Agora 推荐使用 32 字节的密钥。
encryptKdfSalt
:String 型可选参数。盐,长度为 32 字节。Agora 推荐你在服务端使用 OpenSSL 随机生成 Base64 编码的盐,详见媒体流加密。
repeatTime
:Int 型可选参数。播放媒体流次数。该参数仅对点播流有效。可设为:
1
:(默认)播放媒体流一次。-1
:循环播放媒体流。n
:自定义播放媒体流次数。整型,不可设置为 0。所有可能的响应状态码详见状态码汇总表。
X-Request-ID
:UUID(通用唯一识别码),标识本次请求。该值为本次请求 header 中 X-Request-ID
。如果请求出错,请在日志中打印出该值,排查问题。
如果本次请求的响应状态码为
401(Unauthorized)
,那么响应 header 中无该字段。
X-Resource-ID
:UUID(通用唯一识别码),标识本次请求创建的云端播放器的 ID:
409(Conflict)
时,代表本次创建的播放器名字已经存在的播放器名字重复,该字段为那个同名播放器的 ID。请检查并修改本次创建的播放器名字。使用 Number 型用户名(uid
)的示例:
{
"player": {
"uid": 101,
"id": "2a784467d647bb87b60b719f6fa56317",
"createTs": 1575508644,
"status": "running"
},
"fields": "player.uid,player.id,player.createTs,player.status"
}
使用 String 型用户名(account
)的示例:
{
"player": {
"account": "teacher101",
"id": "2a784467d647bb87b60b719f6fa56333",
"createTs": 1575508655,
"status": "running"
},
"fields": "player.account,player.id,player.createTs,player.status"
}
如果状态码为 2XX,请求成功。Body 中包含如下字段:
player
:JSON Object 类型,包含如下字段:uid
:Number 型字段。返回设置的云端播放器在频道内的 UID。account
:String 型字段。返回设置的云端播放器在频道内的用户 Account。id
:String 型字段。云端播放器的 ID。它是 Agora 服务器生成的一个 UUID(通用唯一识别码),标识已创建的一个云端播放器。createTs
:Number 型字段。云端播放器创建的 Unix 时间戳(秒)。status
:String 型字段。云端播放器的运行状态:"idle"
:播放未开始。"connecting"
:Agora 服务器正在连接媒体流地址或正在探测音视频数据。"running"
:正在播放。"failed"
:Agora 服务器无法连接媒体流地址或该媒体流无法播放。fields
:String 型字段。JSON 编码方式的字段掩码,详见谷歌 protobuf FieldMask 文档。用于指定返回 player
字段的子集。在使用 uid
的示例中,fields
指定了 Agora 服务器返回 player
字段中的 uid
,id
,createTS
和 status
字段子集。如果状态码不为 2XX,请求失败。Body 中包含 String 类型的 message
字段,描述失败的具体原因。
{
"message": "Resource with the same name already exists."
}
DELETE https://api.agora.io/{region}/v1/projects/{appId}/cloud-player/players/{id}
appId
:String 型必填参数。Agora 为每个开发者提供的 App ID。在 Agora 控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。id
:String 型必填参数。云端播放器的 ID。region
: String 型必填参数。Cloud Player 所在的区域。必须与创建 Cloud Player 设置的 region
一致。Authorization
:该字段的值需参考认证说明。
X-Request-ID
:UUID(通用唯一识别码),标识本次请求。传入该字段后,Agora 服务器会在响应 header 中返回该字段。
Agora 推荐用户对
X-Request-ID
赋值。如果用户不赋值,Agora 服务器会自动生成一个 UUID 传入。
空
所有可能的响应状态码详见状态码汇总表。
Delete 一个已经销毁过的云端播放器,响应状态码也为 2XX。
X-Request-ID
:UUID(通用唯一识别码),标识本次请求。该值为本次请求 header 中 X-Request-ID
。如果请求出错,请在日志中打印出该值,排查问题。如果本次请求的响应状态码为
401(Unauthorized)
,那么响应 header 中无该字段。
X-Resource-ID
:UUID(通用唯一识别码),标识本次请求销毁的云端播放器的 ID。同本次请求 URL 中传入的 id
值。如果状态码为 2XX,则请求成功。Body 为空。
如果状态码不为 2XX,请求失败。Body 中包含 String 类型的 message
字段,描述失败的具体原因。
GET https://api.agora.io/v1/projects/{appId}/cloud-player/players
appId
:String 型必填参数。Agora 为每个开发者提供的 App ID。在 Agora 控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。
使用 Query parameters 时的请求 URL 示例:
https://api.agora.io/v1/projects/{appId}/cloud-player/players?filter={filter}&pageSize={pageSize}&pageToken={pageToken}
filter
:String 型可选参数。指定过滤条件。Agora 服务器只列出该项目下符合过滤条件的云端播放器。目前的过滤条件为用户创建播放器时传入的 channelName
。假设用户频道名为 class32
,则将 URL 示例中 filter={filter}
改写为 filter=channelName eq class32
;假设用户频道名为 bigclass
,则将 URL 示例中 filter={filter}
改写为 filter=channelName eq bigclass
。
eq 前后有空格,空格需按照 URL 规范进行 encode。
pageSize
:Number 型可选参数。指定分页大小。取值范围为 1 到 500。默认值为 200,即如果不设值,Agora 服务器将列出单页内至多 200 个云端播放器。
pageToken
:String 型可选参数。指定页码,标明该页的次序。如果不设值,Agora 服务器将返回第一页。
推荐用法:首次使用 List 时,不向该参数传值,得到首页的查询结果和 Agora 服务器返回的
nextPageToken
值。下一次使用 List 时,将nextPageToken
值传入pageToken
查询下一页的云端播放器。
使用以上字段后,Agora 服务器会从指定项目中过滤出符合条件的云端播放器,根据指定的分页大小进行分页,返回指定页码的页面上所有云端播放器。
云端播放器根据创建时间(
createTs
)升序排列。
Authorization
:该字段的值需参考认证说明。
X-Request-ID
:UUID(通用唯一识别码),标识本次请求。传入该字段后,Agora 服务器会在响应 header 中返回该字段。
Agora 推荐用户对
X-Request-ID
赋值。如果用户不赋值,Agora 服务器会自动生成一个 UUID 传入。
空
所有可能的响应状态码详见状态码汇总表。
X-Request-ID
:UUID(通用唯一识别码),标识本次请求。该值为本次请求 header 中 X-Request-ID
。如果请求出错,请在日志中打印出该值,排查问题。
如果本次请求的响应状态码为
401(Unauthorized)
,那么响应 header 中无该字段。
使用 Number 型用户名(uid
)的示例:
{
"totalSize": 10,
"players": [{
"name": "class32_101",
"streamUrl": "rtmp://example.agora.io/live/class32/101",
"channelName": "class32",
"uid": 101,
"id": "2a784467d647bb87b60b719f6fa56317",
"createTs": 1575508644,
"status": "running"
}, {
"name": "class68_422",
"streamUrl": "rtmp://example.agora.io/live/class68/422",
"channelName": "class68",
"uid": 422,
"id": "0b719f6fa563172a784467d647bb87b6",
"createTs": 1575588644,
"status": "connecting"
}],
"fields": "player.name,player.streamUrl,player.channelName,player.uid,player.id,player.createTs,player.status",
"nextPageToken": "7b60b719f"
}
使用 String 型用户名(account
)的示例:
{
"totalSize": 10,
"players": [{
"name": "class33_teacher101",
"streamUrl": "rtmp://example.agora.io/live/class33/teacher101",
"channelName": "class33",
"account": "teacher101",
"id": "2a784467d647bb87b60b719f6fa56333",
"createTs": 1575508655,
"status": "running"
}, {
"name": "class66_teacher422",
"streamUrl": "rtmp://example.agora.io/live/class66/teacher422",
"channelName": "class66",
"account": "teacher422",
"id": "0b719f6fa563172a784467d647bb88b8",
"createTs": 1575509333,
"status": "connecting"
}],
"fields": "player.name,player.streamUrl,player.channelName,player.account,player.id,player.createTs,player.status",
"nextPageToken": "7b60b719f"
}
如果状态码为 2XX,则请求成功。Body 中包含如下字段:
totalSize
:Number 型字段,符合查询条件的云端播放器数量。
players
:JSON Array 型字段,包含如下字段:
个别
player
可能暂时只包含id
,name
,createTs
这三个字段,用户的程序需要能够处理这种情况。
name
:String 型字段。云端播放器的名字。streamUrl
:String 型字段。在线媒体流 URL 地址。channelName
:String 型字段。Agora 频道名称。 uid
:Number 型字段。云端播放器在 Agora 频道内的用户 UID。account
:String 型字段。云端播放器在 Agora 频道内的用户 Account。id
:String 型字段。云端播放器的 ID。它是 Agora 服务器生成的一个 UUID(通用唯一识别码),标识已创建的一个云端播放器。createTs
:Number 型字段。云端播放器创建的 Unix 时间戳(秒)。status
:String 型字段。云端播放器的运行状态:"idle"
:播放未开始。"connecting"
:Agora 服务器正在连接媒体流地址或正在探测音视频数据。"running"
:正在播放。"failed"
:Agora 服务器无法连接媒体流地址或该媒体流无法播放。fields
:String 型字段。JSON 编码方式的字段掩码,详见谷歌 protobuf FieldMask 文档。用于指定返回 players
数组中每个 player 中的字段子集。在使用 uid
的示例中,fields
指定 Agora 服务器返回 players
数组中每个 player 中的 name
,streamUrl
,channelName
,uid
,id
,createTs
和 status
字段子集。
nextPageToken
:String 型字段。本次查询页面的下一页页码,方便用户下一次调用 List
方法继续查询。如果返回的该字段为空字符串,则本次请求已查询到最后一页。
如果状态码不为 2XX,请求失败。Body 中包含 String 类型的 message
字段,描述失败的具体原因。
Agora 服务器限制用户 API 调用速率,超出限制速率时会返回状态码 429(Too Many Requests)
。
API | 限流说明 |
---|---|
Create |
name )的云端播放器时,每个不同名字的云端播放器的创建速率上限为 2 次/秒。name )的云端播放器时,云端播放器的创建速率上限为 50 次/ 秒。 |
Delete |
一个项目中,销毁云端播放器的速率上限为 100 次/秒。 |
List |
filter )时,查询速率上限为 2 次/秒 和 15 次/分钟。filter )时,查询速率上限为 10 次/秒和 20 次/分钟。 |
message
字段内容排查问题。状态码 | 可能的 message 字段内容 |
---|---|
200 OK | / |
400 Bad Request | |
401 Unauthorized | Invalid authentication credentials. |
403 Forbidden | |
404 Not Found | Resource is not found and destroyed. |
409 Conflict | Resource with the same name already exists. |
429 Too Many Requests | |
500 Unknown | Some internal error happened. Contact us to help fix it. |
503 Service Unavailable | |
504 Gateway Timeout | Gateway timeout. Query to check whether the player has been created, or to create another one instead. |
本节总结使用输入在线媒体流 RESTful API 的重要注意事项。
注意事项 | 影响程度 |
---|---|
请确保 Agora 频道场景为直播。 | ★★★☆☆ |
如果你需要同一个频道内仅有一个云端播放器,请你务必使用 name 参数,详见 name 参数解释。 |
★★★☆☆ |
如果你需要同一个频道内有多个云端播放器,请确保每个云端播放器的用户名 UID/Account 都是唯一的,详见 uid 或 account 参数解释。 |
★★★★★ |
请确保将 region 设置为媒体流源站所在区域,详见 region 参数解释。 |
★★★★★ |
云端播放器可能因为服务故障等原因自动销毁。Agora 推荐你开通消息通知服务,监听云端播放器事件。详见上节《回调通知》。 | ★★★★★ |
使用 List 方法时,响应 Body 中的 players 字段有时会仅包含 id , name , CreateTs 这三个字段,请确保你的业务逻辑能够处理这种情况。 |
★★★★★ |
使用 Create /Delete 方法创建/销毁云端播放器,且响应状态码为 504 Gateway Timeout 时,请使用 List 方法查询该云端播放器的真实状况,以防止产生不受管理的云端播放器。 |
★★★☆☆ |
创建云端播放器并收到请求成功的响应报文后,需要等待约 10 秒再使用 List 方法查询,否则可能查询不到任何信息。 |
★★★☆☆ |
请求出错时,请务必在日志中打印出响应 Header 中的 X-Request-ID 和 X-Resource-ID 字段值,以方便排查问题。 |
★★★☆☆ |