文档中心

使用 HTTP 请求调用

最近更新时间：2023.07.10 15:17:20

首次发布时间：2022.03.29 22:10:12

您可使用 API 向企业直播的服务端地址发送请求，并按照接口说明在请求中加入相应请求参数。系统会根据请求的处理情况，返回处理结果。本章节为您介绍企业直播 API 的调用方法，包括但不限于请求结构、公共参数、签名机制和公共错误码。
如果想获得更加便捷的接入体验，推荐您使用 Java SDK 来调用 API。

请求结构

服务地址

API 的服务接入地址，如下表所示。

区域	服务地址
中国大陆	livesaas.volcengineapi.com

通信协议

直播支持通过 HTTP 和 HTTPS 两种方式进行请求通信，推荐使用安全性更高的 HTTPS 方式发送请求。

字符编码

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

请求方法

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

方法	说明
GET	请求服务器返回指定资源。支持将公共信息放置在 header 和 query string 中
POST	请求服务器新增资源或执行特殊操作。仅支持将公共信息放置在 header 中

例如，创建直播间的请求方法为 POST，则其请求 URI 为：

POST http://livesaas.volcengineapi.com/?Action=CreateActivityAPIV2&Version=2020-06-01

构造 URI

请求 URI 的组成结构：{URI-scheme}://{Domain}/?{query-string}。

参数说明如下表所示。

参数	描述
URI-scheme	表示用于传输请求的协议，支持通过 HTTP 和 HTTPS 2 种方式进行请求通信。
Domain	API 的服务接入地址，企业直播的接入地址为 livesaas.volcengineapi.com，适用于中国大陆。
Query-string	查询字符串，包含公共参数和 GET 请求中的查询参数。公共参数：需要包含 Action 和 Version 参数；参数前面需要带一个“?”，公共参数之间用“&”相连。查询参数(GET)：从具体的 OpenAPI 接口文档中获取；查询参数前面需要带一个“?”，形式为“参数名=参数取值”，参数之间用“&”相连。例如“?limit=5”，表示查询不超过 5 条数据。

参数

描述

URI-scheme

表示用于传输请求的协议，支持通过 HTTP 和 HTTPS 2 种方式进行请求通信。

Domain

API 的服务接入地址，企业直播的接入地址为 livesaas.volcengineapi.com，适用于中国大陆。

Query-string

查询字符串，包含公共参数和 GET 请求中的查询参数。

公共参数：需要包含 Action 和 Version 参数；参数前面需要带一个“?”，公共参数之间用“&”相连。
查询参数(GET)：从具体的 OpenAPI 接口文档中获取；查询参数前面需要带一个“?”，形式为“参数名=参数取值”，参数之间用“&”相连。例如“?limit=5”，表示查询不超过 5 条数据。

请求示例

POST http://livesaas.volcengineapi.com/?Action=CreateActivityAPIV2&Version=2020-06-01
{
    "Name":"cool",
    "LiveTime":1642668850
}

返回结果

{
  "ResponseMetadata":{
    "RequestId":"201806041104200100100232280022D30",
    "Action":"CreateActivityAPIV2",
    "Version":"2020-06-01",
    "Service":"livesaas",
    "Region": "cn-north-1"
  },
}

公共参数

在发起请求时，必须携带公共参数，否则请求将无法通过合法性验证。详见公共参数。
有关如何配置企业直播对应的公共请求参数值，详见下表。

名称	类型	是否必填	描述	示例值
Action	String	是	接口名称。实际调用时请参考企业直播对应的 API 文档取值。	ListActivityAPI
Version	String	是	接口版本。实际调用时请参考企业直播对应的 API 文档取值。	2020-06-01
Region	String	是	请求的地域。企业直播的地域固定为 `cn-north-1`。	cn-north-1
Service	String	是	请求的服务名。企业直播的服务名固定为 `livesaas`。	livesaas

签名机制

有关签名机制说明、签名示例以及签名源码示例，详见签名机制、签名示例和签名源码示例。

公共错误码

当调用失败后，响应结果中的 ResponseMetaData.Error 结构体会包含错误码和错误信息。关于错误码和含义请参见公共错误码文档。