You need to enable JavaScript to run this app.
导航
OpenAPI 调用说明
最近更新时间:2023.02.02 18:42:56首次发布时间:2021.11.25 17:24:44

本文介绍了调用慢直播服务端 OpenAPI 的方法,对于具体 OpenAPI 的调用方法,请参考具体的接口说明文档。

前提条件

  1. 通过火山引擎慢直播控制台注册帐号,获取账号的 Access Key ID 和 Secret Access Key (AK/SK),用于 API 请求鉴权。详细步骤,参考 API访问密钥使用指南
  2. 开通慢直播服务,并确保使用的账号具有对应资源的访问权限。

请求结构

调用慢直播服务端 OpenAPI 接口时,是通过向指定服务地址发送请求,并需满足签名信息和具体接口的业务信息来完成的。API 的请求需要包含服务地址、请求方式、请求参数等信息。接口调用成功后,对返回结果进行解析。

以创建空间接口为例,一条未编码的URL请求示例如下:

http://open.volcengineapi.com?Action=GetSpace
&Version=2021-01-01
&<通过header传入的公共请求参数>
&<请求体>

说明如下:

参数/结构说明
https://open.volcengineapi.com请求的通信协议和服务接入地址
Action指定要调用的 API 接口(示例中的 GetSpace 为获取空间信息接口)
Version接口的版本号(慢直播 OpenAPI 的接口版本号固定为 2021-01-01

通过header传入的公共请求参数

系统规定的公共参数,主要包括以下参数:

  • AccessKey:用于 API 请求鉴权的密钥(参考 API 访问密钥使用指南 获取)
  • SecretKey:用于 API 请求鉴权的密钥(参考 API 访问密钥使用指南 获取)
  • ServiceName:OpenAPI 服务名称(慢直播 OpenAPI 的服务名称固定为 aiotvideo
  • Region:OpenAPI 服务所在区域(慢直播 OpenAPI 的服务区域固定为 cn-north-1
请求体调用 OpenAPI 接口需要的业务参数

服务地址

慢直播 OpenAPI 的服务接入地址如下:

服务地域
域名
备注
国内https://open.volcengineapi.com火山引擎 OpenAPI 接入地址

通信协议

慢直播提供的所有接口均通过 HTTPS 进行通信,提供高安全性的通信通道。

请求方式

根据各个接口的具体需求,选择 GET 或 POST 方式发起请求。

请求参数

在发起请求时,请求体中可能会包含两类参数:公共请求参数和接口特有的业务参数。

  • 公共请求参数是每一个接口需要包含的,参考以下公共请求参数说明。
  • 接口特有的业务参数是各个接口特有的,参考各接口的参数描述。

字符编码

请求及返回结果使用 UTF-8 的字符集进行编码。

公共请求参数

公共请求参数是每个接口都需要使用的请求参数,在发送请求时都需要携带这些公共请求参数,否则会导致请求失败。公共请求参数首字母均为大写,以此区分接口特有的请求参数。有关火山引擎 OpenAPI 公共参数的详细说明,参考 公共参数

列表数据

列表数据,均支持传递 PageSizePageNumber 参数,表明查询单页数据的个数以及页码,其中 PageNumber 从 1 开始。

同时在返回值中的最外层,含有 PageNumber, PageSize, 和 TotalCount 三个字段描述数据,以下文档中不再单独说明。

签名机制

对于每一次 HTTPS 协议请求,会根据访问中的签名信息验证访问请求者的身份。具体由用户的火山引擎账号对应的 Access Key ID 和 Secret Access Key(AK/SK)对称加密验证实现。具体的签名机制和方法,参考火山引擎 OpenAPI 签名方法

慢直播 OpenAPI 提供了配套的服务端 SDK,支持多种编程语言,帮助您实现快速开发。建议使用服务端 SDK 来调用 OpenAPI。目前提供的服务端 SDK 实例代码如下:

返回结果

API 请求可返回以下结果:

字段
类型
是否一定返回
说明
ResponseMetadataObject响应元数据;需通过解析该结构体,判断响应结果,参考以下 ResponseMetadata 结构体说明
ResultAny响应数据;调用成功时返回

ResponseMetadata 结构体说明

字段
类型
是否一定返回
说明
RequestIdString请求 ID
ActionStringOpenAPI 接口名称
VersionStringOpenAPI 接口版本
ServiceStringOpenAPI 服务名称
RegionString服务所在地域信息
ErrorObject错误信息;调用失败时返回,参考以下 Error 结构体说明

Error 结构体说明

字段
类型
是否一定返回
说明
CodeNInt64状态码
CodeString状态消息
MessageString具体的错误描述信息

返回结果示例

调用成功

{
    "ResponseMetadata": {
        "RequestId": "202111121413390102111952290700E073",
        "Action": "GetSpace",
        "Version": "2021-01-01",
        "Service": "aiotvideo",
        "Region": "cn-north-1"
    },
    "Result": {
        "SpaceName": "GB001",
        "Description": "",
        "SpaceID": "517ff7ec-7700-4862-b1e7-7967a492df79",
        "Region": "cn-qingdao-a",
        "AccessType": "gb28181",
        "Status": "enabled",
        "vhost": "push-rtmp-2100053143-gb001.push.bfcdnbf.com",
        "Rtmp": {
            "Domain": ""
        },
        "GB": {
            "Domain": "",
            "PullOnDemand": true
        },
        "HLSLowLatency": true,
        "CreatedAt": "2021-11-11T11:28:30+08:00",
        "UpdatedAt": "2021-11-11T11:28:30+08:00",
        "CallbackURL": "",
        "Template": {
            "Screenshot": {
                "TemplateID": "",
                "TemplateName": "",
                "ApplyToALLStream": false
            },
            "Record": {
                "TemplateID": "",
                "TemplateName": "",
                "ApplyToALLStream": false
            }
        }
    }
}

调用失败

{
    "ResponseMetadata": {
        "RequestId": "2021111214171801021219801613010707",
        "Action": "GetSpace",
        "Version": "2021-01-01",
        "Service": "aiotvideo",
        "Region": "cn-north-1",
        "Error": {
            "CodeN": 100009,
            "Code": "InvalidAccessKey",
            "Message": "The security token [] included in the request is invalid."
        }
    }
}