调用 RTMP 网关 RESTful API

前提条件Copy Anchor Link

本文介绍声网 RESTful API 的构成，并引导你如何正确地调用 API。

在调用 RESTful API 之前，请确保已获取声网 App ID 和 Token（可选，用于安全鉴权）；对于服务端产品，还需要获取客户 ID 和客户密钥。可参考开通服务。

配置 URLCopy Anchor Link

以更新流配置模板为例，请求 URL 格式如下：

https://api.sd-rtn.com/{region}/v1/projects/{appId}/rtls/ingress/stream-templates/{templateId}

其中：

• https：通信协议。声网使用 HTTPS 协议。

• api.sd-rtn.com：声网服务端域名。

• {region}/v1/projects/{appid}/rtls/ingress/stream-templates/{templateId}：资源路径。

  • {region}：请求的目标区域，如中国大陆为 cn。
  • v1/projects：API 版本和资源名。
  • {appid}：声网为每个开发者提供的 App ID，是项目的唯一标识。
  • rtls/ingress：代表声网产品或服务，此处为 RTMP 网关服务。
  • stream-templates：指定调用的接口，此处为流配置模板相关接口。
  • {templateId}：指定要操作的对象，此处填入需要更新的流配置模板的 ID。

以上示例仅作参考，你可以参照要调用的 API 的文档，在代码源文件或调试应用中先选择调用方法（如 GET、POST、PUT、PATCH、DELETE），然后根据 API 文档来配置实际的请求 URL。请求 URL 需要区分大小写。

发送请求Copy Anchor Link

请求包括请求 Header 和请求 Body 两部分。在配置完 URL 后，你需要设置请求 Header 和请求 Body 信息，然后向服务器发送请求。

以下是更新流配置模板的请求示例：

curl --location --request PATCH 'https://api.sd-rtn.com/cn/v1/projects/<your_app_id>/rtls/ingress/stream-templates/<templateId>' \
--header 'Accept: application/json' \
--header 'Authorization: <http_basic_auth>' \
--header 'Content-Type: application/json' \
--header 'X-Request-ID: ' \
--data '{
  "settings": {
    "transcoding": {
      "video": {
        "enabled": true,
        "codec": "H.264",
        "width": 1280,
        "height": 720,
        "fps": 24,
        "bitrate": 2200,
        "simulcastStream": {
          "width": 960,
          "height": 540,
          "fps": 24,
          "bitrate": 1670
        }
      }
    }
  }
}'

以上示例仅作参考，你可以参照要调用的 API 的文档，配置实际的请求 Header 和请求 Body 信息。

请求 HeaderCopy Anchor Link

请求 Header 包含了处理请求所需要的信息，比如：

• Accept：告知服务器，客户端可以处理哪些类型的响应，如 application/json。
• Authorization：声网 RESTful API 要求 HTTP 鉴权。每次发送 HTTP 请求时，都必须在请求 Header 部填入 Authorization 字段。关于如何生成该字段的值，请参考实现 HTTP 鉴权。
• Content-Type：指定请求 Body 的类型为 application/json 。
• X-Request-ID：本次请求的 UUID（通用唯一识别码）。

请求 Body（可选）Copy Anchor Link

请求 Body 包含了要发送给服务器的数据。例如，更新一个流配置模板，你需要在请求 Body 中包含模板的参数信息，如是否开启视频转码、编解码格式、帧率等。详情可参考 API 文档的参数描述。请求 Body 需要区分大小写。

接收响应Copy Anchor Link

在发送请求后，声网服务器会对你的请求进行响应。响应包括响应状态码、响应 Header 和响应 Body。

响应状态码Copy Anchor Link

响应的 HTTP 状态码分为 2XX 和非 2XX 两种情况，详情可参考响应状态码。

• 如果返回的 HTTP 状态码为 2XX，表示请求成功。
• 如果 HTTP 状态码不为 2XX，参考响应状态码排查问题。

响应 Header（可选）Copy Anchor Link

响应 Header 指明了响应的标识，用于区分不同请求所收到的响应。常见的响应 Header 包括：

• X-Request-ID，本次请求的 UUID（通用唯一识别码）。

响应 BodyCopy Anchor Link

响应 Body 包含了服务器返回的数据。例如，更新流配置模板的响应 Body 包括请求状态。具体信息以每个 API 的返回值为准。

以下是更新流配置模板的响应示例：

{
  "status": "success"
}

错误处理Copy Anchor Link

当你遇到问题时，可以使用开发者工具查看请求和响应，结合响应状态码进行排查。如未能解决问题，可联系技术支持。