输入在线媒体流 RESTful API

文档中心





互动直播

Agora.io 社区





服务端

平台

Android

iOS

macOS

Web

Windows

框架

小程序

Electron

Unity

Flutter

React Native

Cocos Creator

Cocos2d-x

服务端

产品介绍

快速开始

基础功能

使用 Token 鉴权

进阶功能

服务端功能

频道管理

消息通知服务

输入在线媒体流

推流到 CDN

最佳实践

参考文档

API 参考

校验用户权限

输入在线媒体流 RESTful API

更新时间 2021/07/26 06:50:41

你可以通过 RESTful API 创建云端播放器，将一路在线媒体流作为直播视频源输入到 Agora 频道内。输入成功后，该媒体流会在 Agora 频道内自动播放，供频道内的远端用户欣赏。

开通服务

请提交工单联系声网技术支持开通 Cloud Player 服务。

通过 Basic HTTP 认证

Agora RESTful API 要求 Basic HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入 Authorization 字段。关于如何生成该字段的值，请参考 RESTful API 认证。

工作原理

输入一路在线媒体流至 Agora 频道内播放相当于创建了一个云端播放器（player）。用户可以通过 RESTful API 控制 player，实现对该媒体流的控制：

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 服务器生成。	云端播放器在 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 服务器生成。	云端播放器的运行状态。

Create：创建云端播放器

HTTP 请求

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

使用 Query Parameters 时的请求 URL 示例：
https://api.agora.io/{region}/v1/projects/{appId}/cloud-player/players?streamIp={streamIp}

streamIp ：String 型可选参数。媒体流源站 IP 地址。必须使用有效的 IPv4 地址。该参数可以保障媒体流的传输质量：

如果源媒体流只在 regoin 区域内的部分区域提供服务，请使用该参数。
如果源媒体流可在 regoin 区域内的广泛的区域提供服务，请忽略该参数。

Content-Type ： application/json
Authorization ：该字段的值需参考认证说明。
X-Request-ID：UUID（通用唯一识别码），标识本次请求。传入该字段后，Agora 服务器会在响应 header 中返回该字段。

Agora 推荐用户对 X-Request-ID 赋值。如果用户不赋值，Agora 服务器会自动生成一个 UUID 传入。

请求报文的 Body

使用 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 个字符）：
- 所有小写英文字母（a-z）
- 所有大写英文字母（A-Z）
- 数字 0-9
- 空格
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
uid：Number 型可选字段。云端播放器在 Agora 频道内的用户 UID。取值范围为 0 到（2³²-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：
- 安全性要求一般时，可使用 Agora 控制台生成的临时 Token。
- 安全性要求高时，使用用户服务器生成的正式 Token。
  
  生成正式 Token 时，使用的 uid 或 account 必须和云端播放器的 uid 或 account 取值一致。为确保 Token 永不过期，请直接将 privilegeExpiredTs 设为 0。
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：
- 当 S = T 或 0 时，云端播放器在创建成功时自动播放在线媒体流。
- 当 S > T 时，云端播放器会在 S 时刻开始播放在线媒体流。这种取值方式适用于定时播放。
- 当 S < T 时，如果在线媒体流是直播流，云端播放器在创建成功时直接播放直播流；如果在线媒体流是点播流，云端播放器会从 T - S 时刻（秒）的位置开始播放点播流。这种取值方式适用于应对云端播放器运行出错的场景。举例来说，如果云端播放器 A 在运行中出错，你可以重新创建一个云端播放器 B 并将 playTs 字段设为云端播放器 A 开始播放在线媒体流时的 Unix 时间戳。
name：String 型可选参数。云端播放器的名字。长度必须在 64 个字符以内，支持的字符集范围为：
- 所有小写英文字母（a-z）
- 所有大写英文字母（A-Z）
- 数字 0-9
- "-", "_"
不传值时，name 为空。同一时间，一个项目下可以有多个 name 为空的云端播放器。同一时间，一个项目下不允许出现重名的云端播放器，用户尝试创建同名的云端播放器时会收到响应状态码 409(Conflict)。

HTTP 响应

所有可能的响应状态码详见状态码汇总表。

X-Request-ID：UUID（通用唯一识别码），标识本次请求。该值为本次请求 header 中 X-Request-ID。如果请求出错，请在日志中打印出该值，排查问题。

如果本次请求的响应状态码为 401(Unauthorized)，那么响应 header 中无该字段。
X-Resource-ID：UUID（通用唯一识别码），标识本次请求创建的云端播放器的 ID：
- 响应状态码为 2XX 时，该字段为本次创建的云端播放器的 ID。
- 响应状态码为 409(Conflict) 时，代表本次创建的播放器名字已经存在的播放器名字重复，该字段为那个同名播放器的 ID。请检查并修改本次创建的播放器名字。
- 响应状态码为其他时，该字段为空，本次请求失败。

响应报文的 Body

使用 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：销毁一个云端播放器

HTTP 请求

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 传入。

请求报文的 Body

空

HTTP 响应

所有可能的响应状态码详见状态码汇总表。

Delete 一个已经销毁过的云端播放器，响应状态码也为 2XX。

X-Request-ID：UUID（通用唯一识别码），标识本次请求。该值为本次请求 header 中 X-Request-ID。如果请求出错，请在日志中打印出该值，排查问题。

如果本次请求的响应状态码为 401(Unauthorized)，那么响应 header 中无该字段。

X-Resource-ID：UUID（通用唯一识别码），标识本次请求销毁的云端播放器的 ID。同本次请求 URL 中传入的 id 值。

响应报文的 Body

如果状态码为 2XX，则请求成功。Body 为空。
如果状态码不为 2XX，请求失败。Body 中包含 String 类型的 message 字段，描述失败的具体原因。

List：查询一个项目下所有云端播放器

HTTP 请求

GET https://api.agora.io/v1/projects/{appId}/cloud-player/players

路径参数

appId：String 型必填参数。Agora 为每个开发者提供的 App ID。在 Agora 控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。

Query Parameters

使用 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 传入。

请求报文的 Body

空

HTTP 响应

所有可能的响应状态码详见状态码汇总表。

X-Request-ID：UUID（通用唯一识别码），标识本次请求。该值为本次请求 header 中 X-Request-ID。如果请求出错，请在日志中打印出该值，排查问题。

如果本次请求的响应状态码为 401(Unauthorized)，那么响应 header 中无该字段。

响应报文的 Body

使用 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 字段，描述失败的具体原因。

API 限流说明

Agora 服务器限制用户 API 调用速率，超出限制速率时会返回状态码 429(Too Many Requests)。

API	限流说明
`Create`	一个项目中，创建有名字（`name`）的云端播放器时，每个不同名字的云端播放器的创建速率上限为 2 次/秒。一个项目中，创建没有名字（`name`）的云端播放器时，云端播放器的创建速率上限为 50 次/ 秒。
`Delete`	一个项目中，销毁云端播放器的速率上限为 100 次/秒。
`List`	一个项目中，有过滤条件（`filter`）时，查询速率上限为 2 次/秒和 15 次/分钟。一个项目中，没有过滤条件（`filter`）时，查询速率上限为 10 次/秒和 20 次/分钟。

状态码汇总表

如果状态码为 2XX，则请求成功。
如果状态码不为 2XX，则请求失败。请根据对应的响应报文 Body 中的 message 字段内容排查问题。

状态码	可能的 message 字段内容
200 OK	/
400 Bad Request	Parameter 'streamUrl' is invalid formatted. Parameter channelName is invalid. Fix it in your request and retry.
401 Unauthorized	Invalid authentication credentials.
403 Forbidden	This project has not enabled Cloud Player product yet. Contact us to enable it. This project's permission to use Cloud Player was revoked. Contact us for details.
404 Not Found	Resource is not found and destroyed.
409 Conflict	Resource with the same name already exists.
429 Too Many Requests	Request rate limit exceeded. Resources quota limit exceeded. no available resources
500 Unknown	Some internal error happened. Contact us to help fix it.
503 Service Unavailable	Service overload. Retry with back off strategy, and contact us to help fix it. Service unavailable temporarily. Retry with back off strategy.
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` 字段值，以方便排查问题。	★★★☆☆

开通服务

通过 Basic HTTP 认证

工作原理

Create：创建云端播放器

HTTP 请求

路径参数

Query parameters

请求报文的 Header 字段

请求报文的 Body

HTTP 响应

响应报文的 Header 字段

响应报文的 Body

Delete：销毁一个云端播放器

HTTP 请求

路径参数

请求报文的 Header 字段

请求报文的 Body

HTTP 响应

响应报文的 Header 字段

响应报文的 Body

List：查询一个项目下所有云端播放器

HTTP 请求

路径参数

Query Parameters

请求报文的 Header 字段

请求报文的 Body

HTTP 响应

响应报文的 Header 字段

响应报文的 Body

API 限流说明

状态码汇总表

注意事项