输入在线媒体流 RESTful API

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

开通服务

第一次使用输入在线媒体流，需要开通服务，步骤如下：

1、登录控制台，在项目管理页面，选择需要开通输入在线媒体流服务的项目，点击编辑按钮进入编辑项目页面。 2、在编辑项目页面的功能模块找到输入在线媒体流，点击前往开启输入在线媒体流。 3、点击开启输入在线媒体流。 4、点击确定。

开通成功后你可以在用量页面看到输入在线媒体流的使用情况。

认证

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

原理

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

• Create：在项目中创建一个云端播放器。

• Delete：在项目中销毁一个云端播放器。

• List：分页列出该项目中所有云端播放器。

完整的 player 示例如下：

{
    "name": "class32_101",
    "streamUrl": "rtmp://example.anyrtc.io/live/class32/101",
    "channelName": "class32",
    "account": "101",
    "token": "2a784467d6",
    "idleTimeout": 300,
    "playTs": 1575508644,
    "id": "2a784467d647bb87b60b719f6fa56317",
    "createTs": 1575508644,
    "status": "running"
}

创建云端播放器

HTTP 请求

POST https://api.agrtc.cn/{region}/v1/projects/{appId}/cloud-player/players

路径参数

• appId：String 型必填参数。anyRTC 为每个开发者提供的 App ID。在 anyRTC 控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。
• region: String 型必填参数。创建 Player 的区域。anyRTC 支持分区域创建 Player，目前支持以下区域：
  • cn：中国大陆
  • ap：除中国大陆以外的亚洲区域
  • na：北美
  • eu：欧洲

• 请保证设置的 region 与你的媒体流源站在同一个区域。

• 请保证传入 region 的值为小写。

Query parameters 使用 Query Parameters 时的请求 URL 示例：

POST https://api.agrtc.cn/{region}/v1/projects/{appId}/cloud-player/players?streamIp={streamIp}

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

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

请求报文的 Header 字段

• Content-Type ： application/json

• Authorization ：该字段的值需参考认证说明。

• X-Request-ID：UUID（通用唯一识别码），标识本次请求。传入该字段后，anyRTC 服务器会在响应 header 中返回该字段。

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

请求报文的 Body

{
    "player": {
        "streamUrl": "rtmp://example.anyRTC.io/live/class32/101",
        "channelName": "class32",
        "token": "2a784467d6",
        "account": "101",
        "idleTimeout": 300,
        "playTs": 1575508644,
        "name": "test"
    }
}

请求 Body 为 JSON Object 类型的 player 字段，包含如下字段：

• streamUrl：String 型必填字段。在线媒体流 URL 地址。必须为有效的 HTTP/HTTPS/RTMP/RTSP/HLS 地址，且长度在 1024 个字符以内。
• channelName：String 型必填字段。anyRTC 频道名称。字符串长度必须在 64 字节以内，支持以下字符集（共 89 个字符）：
  • 所有小写英文字母（a-z）
  • 所有大写英文字母（A-Z）
  • 数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
• account：String 型可选字段。限制跟 channelName 一致
• token：String 型可选字段。云端播放器在 anyRTC 频道内使用的动态密钥。如在 anyRTC 控制台未开启权限密钥，则不需要向 token 传值；如在 anyRTC 控制台已启用权限密钥，则必须传入 token，详见服务端生成token
• idleTimeout：Number 型可选字段。云端播放器处于空闲状态的最大时长（秒），即媒体流为非播放状态的最大时长。空闲状态超过设置的 idleTimeout 后，该播放器会自动销毁。取值范围为 5 到 600。默认值为 300。如果取值小于 5，anyRTC 服务器会自动调整为 5；如果取值大于 600，anyRTC 服务器会自动调整为 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 响应

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

响应报文的 Header 字段

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

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

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

响应报文的 Body

{
    "player": {
        "account": "101",
        "id": "2a784467d647bb87b60b719f6fa56317",
        "createTs": 1575508644,
        "status": "running"
    },
    "fields": "player.uid,player.id,player.createTs,player.status"
}

如果状态码为 2XX，请求成功。Body 中包含如下字段：

• player：JSON Object 类型，包含如下字段：
  • account：String 型字段。返回设置的云端播放器在频道内的 UID。
  • id：String 型字段。云端播放器的 ID。它是 anyRTC 服务器生成的一个 UUID（通用唯一识别码），标识已创建的一个云端播放器。
  • createTs：Number 型字段。云端播放器创建的 Unix 时间戳（秒）。
  • status：String 型字段。云端播放器的运行状态：
    • "idle"：播放未开始。
    • "connecting"：anyRTC 服务器正在连接媒体流地址或正在探测音视频数据。
    • "running"：正在播放。
    • "failed"：anyRTC 服务器无法连接媒体流地址或该媒体流无法播放。
• fields：String 型字段。JSON 编码方式的字段掩码，详见谷歌 protobuf FieldMask 文档。用于指定返回 player 字段的子集。

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

{
    "message": "Resource with the same name already exists." 
}   

销毁一个云端播放器

HTTP 请求

DELETE https://api.agrtc.cn/{region}/v1/projects/{appId}/cloud-player/players/{id}

路径参数

• appId：String 型必填参数。anyRTC 为每个开发者提供的 App ID。在 anyRTC 控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。
• id：String 型必填参数。云端播放器的 ID。
• region: String 型必填参数。Cloud Player 所在的区域。必须与创建 Cloud Player 设置的 region 一致。

请求报文的 Header 字段

• Content-Type ： application/json

• Authorization ：该字段的值需参考认证说明。

• X-Request-ID：UUID（通用唯一识别码），标识本次请求。传入该字段后，anyRTC 服务器会在响应 header 中返回该字段。

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

请求报文的 Body

空

HTTP 响应

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

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

响应报文的 Header 字段

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

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

HTTP 请求

GET https://api.agrtc.cn/v1/projects/{appId}/cloud-player/players

路径参数

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

Query Parameters 使用 Query parameters 时的请求 URL 示例：

GET https://api.agrtc.cn/v1/projects/{appId}/cloud-player/players?filter={filter}&pageSize={pageSize}&pageToken={pageToken}

• filter：String 型可选参数。指定过滤条件。anyRTC 服务器只列出该项目下符合过滤条件的云端播放器。目前的过滤条件为用户创建播放器时传入的 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，即如果不设值，anyRTC 服务器将列出单页内至多 200 个云端播放器。

• pageToken：String 型可选参数。指定页码，标明该页的次序。如果不设值，anyRTC 服务器将返回第一页。

推荐用法：首次使用 List 时，不向该参数传值，得到首页的查询结果和 anyRTC 服务器返回的 nextPageToken 值。下一次使用 List 时，将 nextPageToken 值传入 pageToken 查询下一页的云端播放器。

使用以上字段后，anyRTC 服务器会从指定项目中过滤出符合条件的云端播放器，根据指定的分页大小进行分页，返回指定页码的页面上所有云端播放器。

云端播放器根据创建时间（createTs）升序排列。

请求报文的 Header 字段

• Authorization ：该字段的值需参考认证说明。

• X-Request-ID：UUID（通用唯一识别码），标识本次请求。传入该字段后，anyRTC 服务器会在响应 header 中返回该字段。

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

请求报文的 Body

空

HTTP 响应

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

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

响应报文的 Header 字段

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

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

响应报文的 Body

{
    "totalSize": 10,
    "players": [{
        "name": "class32_101",
        "streamUrl": "rtmp://example.anyRTC.io/live/class32/101",
        "channelName": "class32",
        "account": "101",
        "id": "2a784467d647bb87b60b719f6fa56317",
        "createTs": 1575508644,
        "status": "running"
   }, {
        "name": "class68_422",
        "streamUrl": "rtmp://example.anyRTC.io/live/class68/422",
        "channelName": "class68",
        "account": "422",
        "id": "0b719f6fa563172a784467d647bb87b6",
        "createTs": 1575588644,
        "status": "connecting"     
   }],
    "fields": "player.name,player.streamUrl,player.channelName,player.uid,player.id,player.createTs,player.status",
    "nextPageToken": "7b60b719f"
}{
    "totalSize": 10,
    "players": [{
        "name": "class32_101",
        "streamUrl": "rtmp://example.anyRTC.io/live/class32/101",
        "channelName": "class32",
        "account": "101",
        "id": "2a784467d647bb87b60b719f6fa56317",
        "createTs": 1575508644,
        "status": "running"
   }, {
        "name": "class68_422",
        "streamUrl": "rtmp://example.anyRTC.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"
}

如果状态码为 2XX，则请求成功。Body 中包含如下字段：

• totalSize：Number 型字段，符合查询条件的云端播放器数量。
• players：JSON Array 型字段，包含如下字段：

个别 player 可能暂时只包含 id, name, createTs 这三个字段，用户的程序需要能够处理这种情况。

- name：String 型字段。云端播放器的名字。
- streamUrl：String 型字段。在线媒体流 URL 地址。
- channelName：String 型字段。anyRTC 频道名称。
- account：String 型字段。云端播放器在 anyRTC 频道内的用户 UID。
- id：String 型字段。云端播放器的 ID。它是 anyRTC 服务器生成的一个 UUID（通用唯一识别码），标识已创建的一个云端播放器。
- createTs：Number 型字段。云端播放器创建的 Unix 时间戳（秒）。
- status：String 型字段。云端播放器的运行状态：
    - "idle"：播放未开始。
    - "connecting"：anyRTC 服务器正在连接媒体流地址或正在探测音视频数据。
    - "running"：正在播放。
    - "failed"：anyRTC 服务器无法连接媒体流地址或该媒体流无法播放。

• fields：String 型字段。JSON 编码方式的字段掩码，详见谷歌 protobuf FieldMask 文档。用于指定返回 players 数组中每个 player 中的字段子集。
• nextPageToken：String 型字段。本次查询页面的下一页页码，方便用户下一次调用 List 方法继续查询。如果返回的该字段为空字符串，则本次请求已查询到最后一页。

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

API 限制说明

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

状态码汇总表

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

注意事项

本节总结使用输入在线媒体流 RESTful API 的重要注意事项。

• 请确保 anyRTC 频道场景为直播。
• 如果你需要同一个频道内仅有一个云端播放器，请你务必使用 name 参数，详见 name 参数解释。
• 如果你需要同一个频道内有多个云端播放器，请确保每个云端播放器的用户名 account 都是唯一的。
• 请确保将 region 设置为媒体流源站所在区域，详见 region 参数解释。
• 云端播放器可能因为服务故障等原因自动销毁。anyRTC 推荐你开通消息通知服务，监听云端播放器事件。详见下节《输入在线媒体流消息通知服务》。
• 使用 List 方法时，响应 Body 中的 players 字段有时会仅包含 id, name, CreateTs 这三个字段，请确保你的业务逻辑能够处理这种情况。
• 使用 Create/Delete 方法创建/销毁云端播放器，且响应状态码为 504 Gateway Timeout 时，请使用 List 方法查询该云端播放器的真实状况，以防止产生不受管理的云端播放器。
• 创建云端播放器并收到请求成功的响应报文后，需要等待约 10 秒再使用 List 方法查询，否则可能查询不到任何信息。
• 请求出错时，请务必在日志中打印出响应 Header 中的 X-Request-ID 和 X-Resource-ID 字段值，以方便排查问题。