获取新上线设备列表_视频接入服务 VIS_API参考_设备指标统计_华为云

(1)

API 参考

文档版本 01

发布日期 2021-12-27

(2)

非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。

商标声明

和其他华为商标均为华为技术有限公司的商标。

本文档提及的其他所有商标或注册商标，由各自的所有人拥有。

注意

您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示的声明或保证。

由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。

(3)

1 ^{使用前必读}

概述终端节点约束与限制基本概念

1.1 概述

欢迎使用视频接入服务（Video Ingestion Service，简称VIS），该服务提供实时视频数据接入功能，包括摄像头视频数据采集、实时数据分发和视频数据转储等能力。借助视频接入服务，您可以与华为云视频分析服务集成，快速构建基于实时视频数据的智能分析应用。

视频接入服务给用户提供了开放API的方式，您可以根据本文档提供的API来使用服务，支持的全部API请参见API概览。

在调用视频接入服务API之前，请确保已经充分了解视频接入服务相关概念，详细信息请参见产品介绍。

1.2 终端节点

终端节点（Endpoint）即调用API的请求地址，不同服务不同区域的终端节点不同，您可以从地区和终端节点中查询所有服务的终端节点。

视频接入服务的终端节点如表1-1所示，请您根据业务需要选择对应区域的终端节点。

表1-1 视频接入服务终端节点

区域名称区域终端节点（Endpoint）协议类型

华北-北京一 cn-north-1 vis.cn-

north-1.myhuaweicloud.com HTTPS 华北-北京四 cn-north-4 vis.cn-

north-4.myhuaweicloud.com HTTPS

(6)

区域名称区域终端节点（Endpoint）协议类型华东-上海一 cn-east-3 vis.cn-

east-3.myhuaweicloud.com HTTPS 华东-上海二 cn-east-2 vis.cn-

east-2.myhuaweicloud.com HTTPS 华南-广州 cn-south-1 vis.cn-

south-1.myhuaweicloud.com HTTPS

1.3 约束与限制

● RTMP接入功能已下线，若有RTMP视频流接入需求建议您使用视频直播服务。

● 目前"华北-北京一"和"华东-上海二"区域不支持新用户开通。

● VIS支持以下接入类型：

– 视频流：支持HTTP-FLV类型的视频流接入。

– 设备：支持GB/T28181摄像设备接入。

● VIS最多支持接入50个设备，最多支持激活10个视频流。若您需要扩大配额，请提交工单与华为云技术客服联系。

● HTTP-FLV 类型的视频流，支持编码格式为H264。

● GB/T28181摄像设备接入的视频流，支持编码格式为H264和H265。

● RTMP推流地址：RTMP接入类型重新激活后需要再次重新获取最新推流地址。

● 播放地址：HTTP-FLV与RTMP接入类型视频流，每次激活需要重新获取播放地址，同时播放地址存在有效期需要定期获取最新的。

● 视频流的取流地址，最多支持5路同时取流。

● VIS支持以下类型视频流输出：

– HTTP-FLV视频流：当接入到VIS的视频流以H265或H264编码时，输出流支持HTTP-FLV协议。

– HLS视频流：当接入到VIS的视频流以H265或H264编码时，输出流支持HLS 协议。

1.4 基本概念

视频流

在网络上，视频数据按时间先后次序传输和播放的连续视频数据流。

取流

取流是指通过取流地址，从VIS中获取视频流数据的过程。

拉流

拉流是指通过公网环境中的取流地址，获取HTTP-FLV类型的视频流数据，并将其接入到VIS中。

(7)

转储

转储是指根据实时视频流来生成视频文件片段，并存储到OBS中。

HTTP-FLV

一种视频直播协议，将流媒体数据封装成FLV格式，然后通过HTTP协议传输给客户端。

设备

在VIS中，设备指GB/T28181类型设备，是符合国家GB/T28181-2011、GB/

T28181-2016协议标准的网络摄像头（IP Camera，简称IPC）和网络硬盘录像机

（Network Video Recorder，简称NVR）。

凭证

在VIS中，凭证包括访问密钥和GB/T28181密码。

GB/T28181 密码

GB/T28181密码是指GB/T28181类型设备的鉴权密码，主要用于设备接入到VIS时的安全认证，认证方式由GB/T28181协议规定。

设备注册

在VIS中，设备注册是指GB/T28181设备发送注册请求到VIS中。注册成功后，设备处于在线状态。

视频邀约

在VIS中，视频邀约是指当GB/T28181设备处于已注册状态后，VIS向设备发送呼叫请求。邀约成功后，GB/T28181设备将采集的视频流发送到VIS中。

HLS

HLS（HTTP Live Streaming）是由苹果公司提出的基于HTTP的流媒体网络传输协议。

(8)

2 ^{API 概览}

表2-1 VIS API 概览

功能 API 说明

服务开通管理开通服务此接口用于用户申请开通视频接入服

务。

说明：目前"华北-北京一"和"华东-上海二"区域不支持新用户开通。

获取服务开通信息该接口用于获取服务开通信息。

说明：目前"华北-北京一"和"华东-上海二"区域不支持新用户开通。

视频流管理创建视频流该接口用于创建视频流。

更新视频流该接口用于更新视频流的详情，包括

RTMP以及HTTP-FLV类型视频流。对于 GB/T28181设备自动关联的视频流，不能通过该接口进行更新。

删除视频流此接口用于删除指定视频流。

更新转储信息此接口用于更新视频转储信息。创建的

视频流默认没有转储信息，即视频数据不会保存。更新转储信息后可以将视频流保存到指定的存储媒介，如OBS。后续用户可以从OBS上获取到转储的视频。

获取视频流信息此接口用于获取指定视频流的详细信

息。

获取视频流列表此接口用于获取所有视频流的详细信

息。

获取视频流地址此接口用于获取指定视频流的地址。该

地址用于进行视频流推流或者拉流。

设备管理创建GB/T28181设备通

道此接口用于创建GB/T28181设备（摄像

头、网络硬盘录像机等）通道。

(9)

功能 API 说明更新GB/T28181设备通道信息

该接口用于改变通道关联的视频流名称后缀，或者进行“视频邀约”和“取消邀约”，以激活/断开GB/T28181设备的视频传输。

获取设备列表此接口用于获取已注册上的GB/T28181

设备列表。

更新GB/T28181设备通

道接入策略该接口用于设置GB/T28181设备的视频

接入策略。用户可以通过设置接入策略定时自动进行设备的接入。

获取NVR设备通道列表此接口用于获取已注册上的NVR设备通

道列表。

更新NVR设备通道列表该接口用于更新NVR设备的通道列表。

删除GB/T28181设备此接口用于删除指定设备。

凭证管理创建GB/T28181凭证该接口用于创建GB/T28181凭证，该凭

证用于GB/T28181设备注册时使用。

获取GB/T28181凭证列表

该接口用于获取所有GB/T28181凭证。

删除GB/T28181凭证该接口用于删除GB/T28181用户的凭

证。

更新GB/T28181凭证该接口用于更新GB/T28181用户名密码

凭证。

创建AK/SK凭证该接口用于创建AK/SK凭证，AK/SK用于

RTMP视频流推流时的鉴权。

获取AK/SK凭证列表该接口用于获取所有AK/SK凭证。

删除AK/SK凭证该接口用于删除AK/SK凭证。

更新AK/SK凭证该接口用于更新AK/SK凭证。

设备指标统计获取新上线设备列表该接口用于获取今天新上线（即之前没有上线记录）的GB/T28181设备列表。

获取新掉线设备列表该接口用于获取今天新掉线的GB/

T28181设备列表。

获取长期不在线设备列

表该接口用于获取三天以上不在线的GB/

T28181设备列表。

获取近期掉线的设备列表

该接口用于获取状态为“已下线”，且三天内有上线动作的GB/T28181设备。

获取在线未推流设备列表

该接口用于获取曾经在线，且从来没有视频数据推送的GB/T28181设备列表。

(10)

功能 API 说明

获取视频包接收率该接口用于获取当天有视频接入的GB/

T28181设备的平均视频包接受率的列表。

获取曾经上线的设备列

表该接口用于获取曾经上线的GB/T28181

设备列表，即只要上线过的设备信息都会显示。

obs桶策略管理

更新桶授权该接口用于用户更新桶授权。

获取桶信息列表该接口用于用户获取桶信息列表。

(11)

3 ^{如何调用 API}

构造请求认证鉴权返回结果

3.1 构造请求

本节介绍REST API请求的组成，并以调用IAM服务的获取用户Token接口来说明如何调用API，该API获取用户的Token，Token可以用于调用其他API时鉴权。

您还可以通过这个视频教程了解如何构造请求调用API。

请求 URI

请求URI由如下部分组成。

{URI-scheme} :// {Endpoint} / {resource-path} ? {query-string}

表3-1 请求 URI

参数说明

URI-scheme 传输请求的协议，当前所有API均采用HTTPS协议。

Endpoint 承载REST服务端点的服务器域名或IP，不同服务在不同区域时，对应Endpoint不同，可以从终端节点中获取。

例如IAM服务在“华北-北京四”区域的Endpoint为“iam.cn- north-4.myhuaweicloud.com”。

resource-

path 资源路径，即API访问路径。从具体API的URI模块获取，例如“获取用户Token”API的resource-path为“/v3/auth/tokens”。

query-string 查询参数，可选，查询参数前面需要带一个“？”，形式为“参数名=参数取值”，例如“limit=10”，表示查询不超过10条数据。

(12)

例如您需要获取“华北-北京四”区域的Token，则需使用“华北-北京四”区域的 Endpoint（iam.cn-north-4.myhuaweicloud.com），并在获取用户Token的URI部分找到resource-path（/v3/auth/tokens），拼接起来如下所示。

https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens 说明

为查看方便，服务每个具体API的URI，只给出resource-path部分，并将请求方法写在一起。这是因为URI-scheme都是HTTPS，而Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

请求方法

HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。

表3-2 HTTP 方法

方法说明

GET 请求服务器返回指定资源。

PUT 请求服务器更新指定资源。

POST 请求服务器新增资源或执行特殊操作。

DELETE 请求服务器删除指定资源，如删除对象等。

HEAD 请求服务器资源头部。

PATCH 请求服务器更新资源的部分内容。

当资源不存在的时候，PATCH可能会去创建一个新的资源。

在获取用户Token的URI部分，您可以看到其请求方法为“POST”，则其请求为：

POST https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens

请求消息头

附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。

需要添加到请求中的公共消息头如表3-3所示。

表3-3 公共请求消息头

参数名说明是否必选示例

Content-

type 消息体的类型（格式），

默认取值为“application/

json”。

是 application/json

Content-

Length 请求body长度，单位为

Byte。 POST/PUT请

求必填。GET 不能包含。

3495

(13)

参数名说明是否必选示例 X-Project-Id project id，用于不同

project取token。否 e9993fc787d94b6c886 cbaa340f9c0f4

X-Auth-

Token 用户Token，也就是调用获取用户Token接口的响应值，该接口是唯一不需要认证的接口。

否

使用Token认证时必选。

-

X-Sdk-Date 请求的发生时间，格式为 (YYYYMMDD'T'HHMMSS 'Z')。

取值为当前系统的GMT时间。

否

如果使用ak/sk 做接口认证的时候，那么此字段必须设置；如果使用 PKI token的时候，不必设置。

20190307T101459Z

Authorizati

on 签名认证信息。

该值来源于请求签名结果，使用AK/SK进行加密签名的时候需要。

类型：字符串默认值：无

否

使用AK/SK认证时必选。

-

Host 请求的服务器信息，从服务API的URL中获取。

值为hostname[:port]。

端口缺省时使用默认的端口，https的默认端口为 443。

否

使用AK/SK认证时必选。

code.test.com or

code.test.com:443

说明

公有云API同时支持使用AK/SK认证，AK/SK认证是使用SDK对请求进行签名，签名过程会自动往请求中添加Authorization（签名认证信息）和X-Sdk-Date（请求发送的时间）请求头。AK/SK 认证的详细说明请参见API签名指南。

对于获取用户Token接口，由于不需要认证，所以只添加“Content-Type”即可，添加消息头后的请求如下所示。

POST https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

请求消息体

请求消息体通常以结构化格式发出，与请求消息头中Content-type对应，传递除请求消息头之外的内容。若请求消息体中参数支持中文，则中文字符必须为UTF-8编码。

(14)

每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。

对于获取用户Token接口，您可以从接口的请求部分看到所需的请求参数及参数说明。将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写，其中

username

为用户名，

domainname

为用户所属的账号名称，

********

为用户登录密码，

cn-north-4

为project的name，获取方法请参见获取用户名、账号名和项目 name。

说明

scope参数定义了Token的作用域，上面示例中获取的Token仅能访问project下的资源。您还可以设置Token额作用域为某个账号下所有资源或账号的某个project下的资源，详细定义请参见获取用户Token。

POST https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens Content-Type:application/json

{ "auth": { "identity": {

"methods": ["password"], "password": {

"user": {

"name": "username", "password": "**********", "domain": {

"name": "domainname"

} } } }, "scope": { "project": {

"name": "cn-north-4"

} } }}

说明

scope参数定义了Token的作用范围，取值为project或domain，示例中取值为project，表示获取的Token仅能访问指定project下的资源，取值为domainname时，表示获取的token可以访问指定账号下所有资源，scope参数的详细说明，请参见获取用户Token接口。

到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编写代码等方式发送请求调用API。对于获取用户Token接口，返回的响应消息头中“x- subject-token”的值，就是需要获取的用户Token。有了Token之后，您就可以使用 Token认证调用其他API。

3.2 认证鉴权

调用接口有如下两种认证方式，您可以选择其中一种进行认证鉴权。

● Token认证：通过Token认证通用请求。

● AK/SK认证：通过AK（Access Key ID）/SK（Secret Access Key)加密调用请求。

(15)

Token 认证

说明

Token的有效期为24小时，需要使用同一个Token鉴权时，可以缓存起来，避免频繁调用。

Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。

Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限。

Token可通过调用获取用户Token接口获取，调用本服务API需要project级别的 Token，即调用获取用户Token接口时，请求body中“auth.scope”的取值需要选择

“project”，请求示例如下。

{ "auth": { "identity": { "methods": [ "password"

],

"password": { "user": {

"name": "username", "password": "********", "domain": {

"name": "domainname"

} } } }, "scope": { "project": {

"name": "xxxxxxxx"

} } } }

获取Token后，再调用其他接口时，您需要在请求消息头中添加“X-Auth-Token”，

其值即为Token。例如Token值为“ABCDEFJ....”，则调用接口时将“X-Auth-Token:

ABCDEFJ....”加到请求消息头即可，如下所示。

GET https://iam.cn-north-4.myhuaweicloud.com/v3/auth/projects Content-Type: application/json

X-Auth-Token: ABCDEFJ....

您还可以通过这个视频教程了解如何使用Token认证。

AK/SK 认证

说明

AK/SK签名认证方式仅支持消息体大小12MB以内，12MB以上的请求请使用Token认证。

AK/SK认证就是使用AK/SK对请求进行签名，在请求时将签名信息添加到消息头，从而通过身份认证。

● AK(Access Key ID)：访问密钥ID。与私有访问密钥关联的唯一标识符；访问密钥 ID和私有访问密钥一起使用，对请求进行加密签名。

● SK(Secret Access Key)：与访问密钥ID结合使用的密钥，对请求进行加密签名，

可标识发送方，并防止请求被修改。

使用AK/SK认证时，您可以基于签名算法使用AK/SK对请求进行签名，也可以使用专门的签名SDK对请求进行签名。详细的签名方法和SDK使用方法请参见API签名指南。

(16)

须知

签名SDK只提供签名功能，与服务提供的SDK不同，使用时请注意。

3.3 返回结果

请求发送以后，您会收到响应，包含：状态码、响应消息头和响应消息体。

状态码

状态码是一组从1xx到5xx的数字代码，状态码表示了请求响应的状态，完整的状态码列表请参见状态码。

对于获取用户Token接口，如果调用后返回状态码为“201”，则表示请求成功。

响应消息头

对应请求消息头，响应同样也有消息头，如“Content-type”。

表3-4 公共响应消息头

消息头名称说明是否必选

Content-Type 用于指明发送给接收者的实体正文的媒体类型。

类型：字符串。

默认值：application/json; charset=UTF-8

是

X-request-id 此字段携带请求ID号，以便任务跟踪。

类型：字符串。request_id-timestamp-

hostname（request_id在服务器端生成UUID，

timestamp为当前时间戳，hostname为处理当前接口的服务器名称）。

默认值：无。

否

X-ratelimit 此字段携带总计流控请求数。

类型：整型。

默认值：无。

否

X-ratelimit-

used 此字段携带剩下请求数。

类型：整型。

默认值：无。

否

X-ratelimit-

window 此字段携带流控单位。

类型：字符串。单位按照分钟、小时、天。

默认值：小时。

否

对于获取用户Token接口，返回如图获取用户Token相应消息头所示。

(17)

其中“x-subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用 Token认证调用其他API。

图3-1 获取用户 Token 响应消息头

响应消息体

响应消息体通常以结构化格式返回，与响应消息头中Content-type对应，传递除响应消息头之外的内容。

对于获取用户Token接口，返回如下消息体。为篇幅起见，这里只展示部分内容。

{ "token": {

"expires_at": "2019-02-13T06:52:13.855000Z", "methods": [

"password"

],

"catalog": [ {

"endpoints": [ {

"region_id": "cn-north-4", ...

当接口调用出错时，会返回错误码及错误信息说明，错误响应的Body体格式如下所示。

{ "error_msg": "The format of message is error", "error_code": "AS.0001"

}

其中，error_code表示错误码，error_msg表示错误描述信息，具体请参见错误码。

(18)

4 ^{服务开通管理}

开通服务

获取服务开通信息

4.1 开通服务

功能介绍

此接口用于用户申请开通视频接入服务

接口约束

目前"华北-北京一"和"华东-上海二"区域不支持新用户开通

调试

您可以在API Explorer中调试该接口。

URI

POST /v1/{project_id}/subscription

表4-1 路径参数

参数是否必选参数类型描述

project_id 是 String 项目ID，获取方法请参考获取项目ID

(19)

请求参数

表4-2 请求 Header 参数

X-Auth-Token 是 String 普通租户的token。

Authorization 否 String 使用AK/SK方式认证时必选，携带的鉴权信息。

X-Sdk-Date 否 String 使用AK/SK方式认证时必选，请求的发生时间。

X-Project-Id 否 String 使用AK/SK方式认证时必选，携带项目ID信息。

响应参数

状态码： 201

表4-3 响应 Body 参数

参数参数类型描述

user_id String 用户ID。

sip_ip String SIP服务器地址，VIS对外提供的设备注册地址。

sip_port String SIP服务器端口，VIS对外提供的设备注册端口，

固定为5080。

quota quotaInfo

object 开通服务返回的quota体。

created_at String 创建时间，格式为：YYYY-MM-DDTHH:MM:SSZ

（UTC时间）。

is_subscribed Boolean 用户是否开通服务。

● true：表示开通。

● false：表示未开通。

表4-4 quotaInfo

password PassWordInf

o object GB/T28181凭证配额信息。

(20)

参数参数类型描述 consecutive_a

ccess_time Consecutive_

Access_TimeI nfo object

GB/T28181设备连续接入时长的配额信息。

random_acces

s_time Random_Acc ess_TimeInfo object

GB/T28181设备随机接入时长的配额信息。

stream StreamInfo

object 视频流配额信息。

active_stream Active_Strea

mInfo object 激活视频流配额信息。

device DeviceInfo

object 设备配额信息。

aksk AKSKInfo

object AKSK凭证配额信息。

http_num HttpInfo

object http_flv配额信息。

http_active_n

um HttpActiveInf

o object http_flv激活配额信息。

rtmp_num RtmpInfo

object rtmp配额信息。

表4-5 PassWordInfo

total Integer GB/T28181凭证总配额量。

used Integer GB/T28181凭证已创建量。

表4-6 Consecutive_Access_TimeInfo

total Integer 设备连续接入的总时长。

used Integer 设备已使用的时长。

(21)

表4-7 Random_Access_TimeInfo

total Integer GB/T28181设备随机接入的总时长。

used Integer GB/T28181设备随机已接入的时长。

表4-8 StreamInfo

total Integer 视频流总配额量。

used Integer 视频流已创建量。

表4-9 Active_StreamInfo

total Integer 可激活视频流总配额量。

used Integer 视频流已激活量。

表4-10 DeviceInfo

total Integer 设备总配额量。

used Integer 设备已创建量。

表4-11 AKSKInfo

total Integer AKSK凭证总配额量。

used Integer AKSK凭证已创建量。

表4-12 HttpInfo

total Integer http_flv总配额数量 used Integer http_flv已创建数量

(22)

表4-13 HttpActiveInfo

total Integer http_flv激活总配额数量 used Integer http_flv已激活数量

表4-14 RtmpInfo

total Integer rtmp总配额数量 used Integer rtmp已创建数量

请求示例

POST /v1/3266392d188c47d09948b1**********/subscription

响应示例

状态码： 201 请求响应成功

{ "user_id" : "******6045184a8194e021113e******", "sip_ip" : "10.95.144.***",

"sip_port" : "5080", "quota" : {

"consecutive_access_time" : { "total" : 120,

"used" : 0 },

"password" : { "total" : 10, "used" : 0 },

"random_access_time" : { "total" : 240,

"used" : 0 },

"stream" : { "total" : 50, "used" : 0 },

"active_stream" : { "total" : 10, "used" : 0 },

"device" : { "total" : 50, "used" : 0 },

"aksk" : { "total" : 10, "used" : 0 },

"http_num" : {

(23)

"total" : 10, "used" : 0 },

"http_active_num" : { "total" : 5,

"used" : 0 },

"rtmp_num" : { "total" : 0, "used" : 0 }

}, "created_at" : "2018-10-25T03:06:10Z", "is_subscribed" : true

}

状态码： 400

请求错误。具体返回错误码请参考错误码说明

{ "error_msg" : "You have already subscribed to VIS.", "error_code" : "VIS.0018"

}

状态码

状态码描述

201 请求响应成功

400 请求错误。具体返回错误码请参考错误码说明

4.2 获取服务开通信息

功能介绍

该接口用于获取服务开通信息

接口约束

目前"华北-北京一"和"华东-上海二"区域不支持新用户开通

调试

URI

GET /v1/{project_id}/subscription

(24)

表4-15 路径参数

请求参数

响应参数

状态码： 200

user_id String 用户ID。

sip_ip String SIP服务器地址，VIS对外提供的设备注册地址。

sip_port String SIP服务器端口，VIS对外提供的设备注册端口，

固定为5080。

quota quotaInfo

object 开通服务返回的quota体。

created_at String 创建时间，格式为：YYYY-MM-DDTHH:MM:SSZ

（UTC时间）。

is_subscribed Boolean 用户是否开通服务。

● true：表示开通。

● false：表示未开通。

(25)

表4-18 quotaInfo

password PassWordInf

o object GB/T28181凭证配额信息。

consecutive_a

ccess_time Consecutive_

Access_TimeI nfo object

GB/T28181设备连续接入时长的配额信息。

random_acces

s_time Random_Acc ess_TimeInfo object

GB/T28181设备随机接入时长的配额信息。

stream StreamInfo

object 视频流配额信息。

active_stream Active_Strea

mInfo object 激活视频流配额信息。

device DeviceInfo

object 设备配额信息。

aksk AKSKInfo

object AKSK凭证配额信息。

http_num HttpInfo

object http_flv配额信息。

http_active_n

um HttpActiveInf

o object http_flv激活配额信息。

rtmp_num RtmpInfo

object rtmp配额信息。

表4-19 PassWordInfo

total Integer GB/T28181凭证总配额量。

used Integer GB/T28181凭证已创建量。

表4-20 Consecutive_Access_TimeInfo

total Integer 设备连续接入的总时长。

used Integer 设备已使用的时长。

(26)

表4-21 Random_Access_TimeInfo

total Integer GB/T28181设备随机接入的总时长。

used Integer GB/T28181设备随机已接入的时长。

表4-22 StreamInfo

total Integer 视频流总配额量。

used Integer 视频流已创建量。

表4-23 Active_StreamInfo

total Integer 可激活视频流总配额量。

used Integer 视频流已激活量。

表4-24 DeviceInfo

total Integer 设备总配额量。

used Integer 设备已创建量。

表4-25 AKSKInfo

total Integer AKSK凭证总配额量。

used Integer AKSK凭证已创建量。

表4-26 HttpInfo

total Integer http_flv总配额数量 used Integer http_flv已创建数量

(27)

表4-27 HttpActiveInfo

total Integer http_flv激活总配额数量 used Integer http_flv已激活数量

表4-28 RtmpInfo

total Integer rtmp总配额数量 used Integer rtmp已创建数量

请求示例

GET /v1/3266392d188c47d09948b1**********/subscription

响应示例

{ "user_id" : "******6045184a8194e021113e******", "sip_ip" : "10.95.144.***",

"sip_port" : "5080", "quota" : {

"consecutive_access_time" : { "total" : 120,

"used" : 120 },

"password" : { "total" : 10, "used" : 2 },

"random_access_time" : { "total" : 240,

"used" : 240 },

"stream" : { "total" : 500, "used" : 8 },

"active_stream" : { "total" : 200, "used" : 4 },

"device" : { "total" : 500, "used" : 0 },

"aksk" : { "total" : 10, "used" : 6 },

"http_num" : {

(28)

"total" : 10, "used" : 5 },

"http_active_num" : { "total" : 5,

"used" : 1 },

"rtmp_num" : { "total" : 0, "used" : 0 }

}, "created_at" : "2018-10-25T03:06:10Z", "is_subscribed" : true

}

状态码： 404

找不到资源或没有开通服务。具体返回错误码请参考错误码说明

{ "error_msg" : "Failed to find the user subscription info.", "error_code" : "VIS.0015"

}

状态码

状态码描述

404 找不到资源或没有开通服务。具体返回错误码请参考错误码说明

(29)

5 ^{视频流管理}

创建视频流获取视频流列表更新视频流获取视频流信息删除视频流更新转储信息获取视频流地址

5.1 创建视频流

功能介绍

该接口用于创建视频流。包括RTMP以及HTTP-FLV类型视频流。

● 创建RTMP视频流时，用户可根据实际需求选择是否配置秘钥，如果配置了秘钥，

则进行RTMP推流时需要提供认证Token。如果不配置该参数，则推流时不需要进行认证。

● 创建HTTP-FLV视频流时，需要HTTP-FLV视频流的拉流地址，且地址必须是http或 https协议的合法URL。

自定义流名称只能使用英文字母a~z，A-Z）、数字（0~9）以及连接符（-、_），连接符（-、__）不能连续出现、不能单独注册，也不能放在开头和结尾。长度不低于 8，不超过128个字符。

调试

URI

POST /v1/{project_id}/streams

(30)

表5-1 路径参数

请求参数

表5-3 请求 Body 参数

name 是 String 自定义流名称只能使用英文字母

a~z，A-Z）、数字（0~9）以及连接符（-、_），连接符（-、

__）不能连续出现、不能单独注册，也不能放在开头和结尾。长度不低于 8，不超过128个字符。

access_type 是 String 视频接入类型，当前支持HTTP- FLV和RTMP协议，不区分大小写。

encode_type 是 String 视频流编码格式，当前支持 H264，不区分大小写。

(31)

share_type 否 String 视频流共享类型。

● PRIVATE：非共享。

● PUBLIC：共享。

不填时默认为PRIVATE，不区分大小写。当值为PRIVATE，用户在拉取视频时会鉴权，拉流时必须在请求头中添加X-Auth- Token，值为创建视频流的用户的Token。拉流地址参考获取视频流地址。

url 否 String 当视频类型为RTMP协议时，不

需要该参数。当视频类型为 HTTP-FLV协议时，该参数必填，表示HTTP-FLV协议视频流的拉流地址。该地址必须是http 或https协议的合法URL，格式要求以“http://”或

“https://”开头的字符串，例如“http://xxxx.xxx”。

access_key 否 String 当视频类型为HTTP-FLV时，不需要该参数。视频接入类型是 RTMP时，该参数表示秘钥 access_key，用户可根据自己实际需求选择是否配置。如果配置了秘钥access_key，则进行 RTMP推流时需要提供认证 Token。这里的秘钥access_key 由创建AK/SK凭证接口生成。配置了秘钥access_key后，在推流时，需要在原始推流地址后面加上若干查询参数，作为推流认证信息,具体请参见推流鉴权规则。如果不配置该参数，表示不提供access_key，则推流时不需要进行认证。

description 否 String 视频流的描述信息，可填字符串最大长度为500。

tag 否 Array of

StreamTag objects

和视频流关联的标签，一个视频流最多添加10个标签。

(32)

表5-4 StreamTag

key 否 String 标签的键。最大长度为36个

UNICODE字符（一-鿿），可以包含大小写字母、数字、中划线

（-）或者下划线（_），不能包含其他的特殊字符。

value 否 String 标签的值。最大长度为43个

UNICODE字符（一-鿿），可以包含大小写字母、数字、点

（.）、中划线（-）或者下划线

（_），不能包含其他的特殊字符，也可以为空字符串。

响应参数

状态码： 201

stream_id String 视频流ID。

name String 视频流的名称。

encode_type String 视频流编码格式。

access_type String 视频接入类型。

access_key String RTMP视频流的密钥。接入类型（access_type）

为RTMP时，才有该参数。

url String HTTP-FLV视频流的拉流地址。接入类型

（access_type）为HTTP-FLV时，才有该参数。

share_type String 视频流共享类型。

state String 视频流状态。

● ACTIVE：表示已激活。

● STOPPED：表示已停用。

默认为STOPPED。

created_at String 视频流创建时间，UTC时间，格式为：YYYY- MM-DDTHH:MM:SSZ。

updated_at String 视频流更新时间，UTC时间，格式为：YYYY- MM-DDTHH:MM:SSZ。

description String 视频流描述信息。

(33)

参数参数类型描述 tag Array of

和视频流关联的标签。

key String 标签的键。最大长度为36个UNICODE字符（一-

鿿），可以包含大小写字母、数字、中划线（-）

或者下划线（_），不能包含其他的特殊字符。

value String 标签的值。最大长度为43个UNICODE字符（一-

鿿），可以包含大小写字母、数字、点（.）、中划线（-）或者下划线（_），不能包含其他的特殊字符，也可以为空字符串。

请求示例

● RTMP

POST /v1/3266392d188c47d09948b1**********/streams { "name" : "stream_test1",

"access_type" : "RTMP", "encode_type" : "H264", "share_type" : "PUBLIC",

"access_key" : "ALKJOWLKJSDNFGO******KSJDF", "description" : "",

"tag" : [ { "key" : "group", "value" : "number1"

} ] }

● HTTP-FLV

POST /v1/3266392d188c47d09948b1**********/streams { "name" : "stream_test2",

"access_type" : "HTTP-FLV", "encode_type" : "H264", "share_type" : "PUBLIC",

"url" : "https://xxxxxxxx.com/live", "description" : "",

} ] }

响应示例

(34)

● 示例 1

{ "stream_id" : "stream-0BOPSRsT", "name" : "stream_test1",

"encode_type" : "H264", "access_type" : "RTMP",

"access_key" : "ALKJOWLKJSDNFGO******KSJDF", "share_type" : "PUBLIC",

"state" : "STOPPED",

"created_at" : "2018-06-12T13:00:01Z", "updated_at" : "2018-06-12T13:00:01Z", "description" : "",

} ] }

● 示例 2

{ "stream_id" : "stream-9IzU3TdL", "name" : "stream_test2", "encode_type" : "H264", "access_type" : "HTTP-FLV", "url" : "https://xxxxxxxx.com/live", "share_type" : "PUBLIC",

"created_at" : "2018-06-12T13:00:01Z", "updated_at" : "2018-06-12T13:00:01Z", "description" : "",

} ] }

状态码： 400

{ "error_msg" : "Invalid request parameter, url can not be null or empty when access type is HTTP-FLV.", "error_code" : "VIS.0005"

}

状态码

状态码描述

5.2 获取视频流列表

功能介绍

此接口用于获取所有视频流的详细信息。

(35)

调试

URI

GET /v1/{project_id}/streams

表5-7 路径参数

表5-8 Query 参数

offset 否 Integer 查询的开始位置，取值范围为0

～100000，必须与limit一起使用。与limit同时缺省时，返回所有结果。该参数适用于所有查询列表的接口。如果offset超过数据总条数，则结果返回空列表。

limit 否 Integer 返回结果的最大条目数，取值范

围为1～1000，必须与offset一起使用。与offset同时缺省时，

返回所有结果。该参数适用于所有查询列表的接口。

sort 否 String 返回结果的排序规则。

● ASC：表示升序。

● DESC：表示降序。

默认为ASC，需要有offset和 limit参数，sort参数才会生效。

(36)

order_by 否 String 选择按一个字段排序，可选值如下。

● encode_type：视频流编码格式。

● access_type：视频接入类型。

● share_type：视频流共享类型。

● created_at：视频流创建时间。

● name：视频流名字。

● state：视频流状态。

● retention_state：视频流转储状态。

默认为created_at，按照创建时间排序。需要有offset和limit参数，order_by参数才会生效。

name 否 String 按照视频流名称过滤，支持模糊

查询。

stream_state 否 String 按视频流状态过滤，可选值如下。

● STOPPED：表示未激活。

不区分大小写。

retention_stat

e 否 String 按视频流转储状态过滤，可选值

如下。

● ACTIVE：表示已启用转储。

● STOPPED：表示未启用转储。

请求参数

(37)

响应参数

状态码： 200

total Integer 视频流总数 entries Array of

StreamRespo nseList objects

视频流数组

表5-11 StreamResponseList

name String 视频流名称。

access_type String 视频接入类型。

url String HTTP-FLV视频流的地址。接入类型

transfer_proto

col String GB视频传输协议（TCP|UDP）。只有当视频介入类型为GB/T28181时，才有该参数。

(38)

参数参数类型描述 retention retention

object 视频流转储信息。

retention_stat

e String 按视频流转储状态过滤，可选值如下。

created_at String 视频流创建时间。

updated_at String 视频流更新时间。

表5-12 retention

retention_in_h

our Integer 保存时长，以小时为单位。

Retention_for

ever Boolean 是否永久保存。

store_type String 转储位置，可为“obs”，即存储到华为云对象存储OBS上。

bucket String OBS桶名。

path String OBS目录。

timezone String 时区信息。

slice_in_minut

e Integer 分片长度，以分钟为单位。取值范围为1～60，

默认为5。

请求示例

GET /v1/3266392d188c47d09948b1**********/streams

响应示例

{ "total" : 273, "entries" : [ {

"access_type" : "RTMP",

"updated_at" : "2018-12-25T12:59:37Z", "share_type" : "PUBLIC",

"stream_id" : "stream-0BOPSRsT",

"access_key" : "ALKJOWLKJSDNFGO******KSJDF", "name" : "stream_test1",

(39)

"created_at" : "2018-12-25T12:59:37Z", "description" : "",

"state" : "ACTIVE",

"retention_state" : "ACTIVE", "tag" : [ {

"key" : "group"

}, {

"value" : "number1"

} ],

"retention" : {

"bucket" : "iva-ly-test", "path" : "testRetention", "timezone" : "GMT+08:00", "retention_in_hour" : 1, "retention_forever" : false, "store_type" : "OBS", "slice_in_minute" : 5 },

"encode_type" : "H264"

}, {

"access_type" : "HTTP-FLV",

"stream_id" : "stream-9IzU3TdL", "url" : "https://xxxxxxxx.com/live", "name" : "RTMP******",

"created_at" : "2018-12-25T12:59:37Z", "description" : "",

"state" : "ACTIVE",

"retention_state" : "ACTIVE", "tag" : [ {

"key" : "group", "value" : "number1"

} ],

"retention" : {

"bucket" : "iva-ly-test", "path" : "testRetention/", "timezone" : "GMT+08:00", "retention_in_hour" : 1, "retention_forever" : false, "store_type" : "OBS", "slice_in_minute" : 5 },

}, {

"access_type" : "GB/T28181",

"stream_id" : "stream-0P5g9fQ2", "access_key" : "0000",

"name" : "channel_9339084235132000****", "created_at" : "2018-12-25T10:52:00Z", "description" : "",

"retention_state" : "STOPPED", "tag" : [ ],

} ] }

状态码： 400

}

(40)

状态码

状态码描述

5.3 更新视频流

功能介绍

该接口用于更新视频流的详情，包括RTMP以及HTTP-FLV类型视频流。

接口约束

当视频流处于ACTIVE状态时，不允许修改视频接入类型

调试

URI

PUT /v1/{project_id}/streams/{stream_name}

表5-13 路径参数

stream_name 是 String 视频流名称

请求参数

(41)

access_type 否 String 视频接入类型，例如HTTP- FLV、RTMP等，不区分大小写。当视频流处于ACTIVE状态时，不允许修改该项。

encode_type 否 String 视频流编码格式，当前支持 H264，不区分大小写。

access_key 否 String RTMP视频流绑定的秘钥Access Key。

url 否 String HTTP-FLV视频流的拉流地址。

URL必须是http或https协议的合法URL。格式要求：以

“http://”或“https://”开头的字符串，例如“http://

xxxx.xxx”。

description 否 String 视频流的描述信息。

share_type 否 String 视频流共享类型。

tag 否 Array of

和视频流关联的标签，一个视频流最多添加10个标签。

state 否 String 视频流状态,可选值如下。

(42)

key 否 String 标签的键。最大长度为36个

UNICODE字符（一-鿿），可以包含大小写字母、数字、中划线

（-）或者下划线（_），不能包含其他的特殊字符。

value 否 String 标签的值。最大长度为43个

UNICODE字符（一-鿿），可以包含大小写字母、数字、点

（.）、中划线（-）或者下划线

（_），不能包含其他的特殊字符，也可以为空字符串。

响应参数

状态码： 200

result String 处理成功时返回

请求示例

PUT /v1/3266392d188c47d09948b1**********/streams/streamTest { "state" : "ACTIVE"

}

响应示例

{ "result" : "success"

}

状态码： 400

}

(43)

状态码

状态码描述

5.4 获取视频流信息

功能介绍

此接口用于获取指定视频流的详细信息。

说明：Stream_Flow_Info中部分字段数据暂时无法提供，数据内容无意义。

调试

URI

GET /v1/{project_id}/streams/{stream_name}

表5-18 路径参数

请求参数

(44)

响应参数

状态码： 200

access_type String 视频接入类型（例如HTTP-FLV、RTMP、GB/

T28181）。

updated_at String 视频流更新时间。

url String HTTP-FLV视频流的地址。接入类型

transfer_proto

col String GB视频传输协议（TCP|UDP）。只有当视频接入类型为GB/T28181时，才有该参数。

name String 视频流名称。

created_at String 视频流创建时间。

description String 视频流描述信息。

默认为STOPPED。

tag Array of StreamTag objects

和视频流关联的标签。

retention retention

object 视频转储信息。

stream_flow_i

nfo Stream_Flow

_Info object 视频流详细信息。

retention_stat

e String 按视频流转储状态过滤，可选值如下。

(45)

key String 标签的键。最大长度为36个UNICODE字符（一-

鿿），可以包含大小写字母、数字、中划线（-）

或者下划线（_），不能包含其他的特殊字符。

value String 标签的值。最大长度为43个UNICODE字符（一-

鿿），可以包含大小写字母、数字、点（.）、中划线（-）或者下划线（_），不能包含其他的特殊字符，也可以为空字符串。

表5-22 retention

retention_in_h

our Integer 保存时长，以小时为单位。

Retention_for

ever Boolean 是否永久保存。

store_type String 转储位置，可为“obs”，即存储到华为云对象存储OBS上。

bucket String OBS桶名。

path String OBS目录。

timezone String 时区信息。

slice_in_minut

e Integer 分片长度，以分钟为单位。取值范围为1～60，

默认为5。

表5-23 Stream_Flow_Info

is_publishing Boolean 视频流是否在推流/拉流。

● RTMP类型: 表示是否正在推流。

● HTTP-FLV类型: 表示是否正在从URL中拉取视频数据。

bw_out String 出流带宽。正在推流（即is_publishing为true）

时会返回该字段。

注：暂时无法提供该数据，数据内容无意义。

(46)

bw_in String 推流码率。正在推流（即is_publishing为true）

bw_video String 视频带宽。正在推流（即is_publishing为true）

bw_audio String 音频带宽。正在推流（即is_publishing为true）

bytes_out String 出流总量。

bytes_in String 入流总量。

num_play_clie

nts String 正在拉取该视频流数据的客户端数量。正在推流 (即is_publishing为true)时会返回该字段。

meta Video object 实时推流视频流元数据。正在推流(即

is_publishing为true)时会返回该字段。

表5-24 Video

video VideoInfo

object 推流视频流视频相关数据。

表5-25 VideoInfo

codec String 视频编码格式。

width String 视频分辨率水平方向像素。

height String 视频分辨率垂直方向像素。

请求示例

GET /v1/3266392d188c47d09948b1**********/streams/stream1

响应示例

状态码： 200

(47)

请求响应成功

{ "access_type" : "RTMP",

"stream_id" : "stream-0P5g9fQ2",

"access_key" : "ALKJOWLKJSDNFGO******KSJDF", "name" : "stream_test1",

"description" : "", "state" : "ACTIVE", "tag" : [ { "key" : "group", "value" : "number1"

} ],

"retention" : {

"bucket" : "iva-ly-test", "path" : "testRetention/", "timezone" : "GMT+08:00", "retention_in_hour" : 1, "retention_forever" : false, "store_type" : "OBS", "slice_in_minute" : 5, "state" : "ACTIVE"

}, "stream_flow_info" : { "bw_out" : "100 Kb/s", "bw_in" : "100 Kb/s", "bytes_out" : "131.469 MB", "bw_video" : "100 Kb/s", "bytes_in" : "110.28 MB", "num_play_clients" : 2, "bw_audio" : "100 Kb/s", "is_publishing" : true, "meta" : {

"video" : { "codec" : "H264", "width" : 400, "height" : 600 }

}

}, "encode_type" : "H264"

}

状态码： 400

{ "error_msg" : "The entered stream ID does not exist.", "error_code" : "VIS.0202"

}

状态码

状态码描述

(48)

5.5 删除视频流

功能介绍

此接口用于删除指定视频流。

调试

URI

DELETE /v1/{project_id}/streams/{stream_name}

表5-26 路径参数

请求参数

响应参数

状态码： 200

(49)

请求示例

DELETE /v1/3266392d188c47d09948b1**********/streams/streamTest

响应示例

{ "result" : "success"

}

状态码： 400

{ "error_msg" : "The entered stream name %s does not exist.", "error_code" : "VIS.0202"

}

状态码

状态码描述

5.6 更新转储信息

功能介绍

此接口用于更新视频转储信息。创建的视频流默认没有转储信息，即视频数据不会保存。更新转储信息后可以将视频流保存到指定的存储媒介，如OBS。后续用户可以从 OBS上获取到转储的视频。

● 如果转储到OBS，在调用该API之前，需要您先授予VIS操作OBS的权限，授权操作只需要操作一次即可，后续转储无需再操作。授权方法如下：

a. 登录视频接入服务控制台。

b. 在"视频流管理"页面，找到您需要转储的已激活视频流，单击操作列的"开始转储"。

c. 如果您之前没有OBS授权，则系统会提示您进行OBS授权，单击"同意授权"即可。

(50)

● 如果转储到OBS，最终生成的视频文件路径为 "/OBS路径/视频流名称/year/

month/day/hour/startmin.sec_endmin.sec.flv，例如obs:path/to/video/

streamName/2018/8/18/18/0000_0200.flv。"

调试

URI

PUT /v1/{project_id}/streams/{stream_name}/retention

表5-29 路径参数

请求参数

store_type 否 String 视频转储位置，可为“obs”，

即存储到云服务OBS上。第一次创建转储信息时必选，不区分大小写。

bucket 否 String OBS桶名，当“store_type”为

“obs”时必选。

(51)

path 否 String OBS目录，当“store_type”为

“obs”时，该参数必选。该目录下的文件夹最多为N+2个，N 为转储时长。

slice_in_minut

e 否 Integer 分片长度，以分钟为单位。取值

范围为1～60，默认为5。

timezone 是 String 当地时区。格式为GMT+HH:

00，如GMT+8:00表示东八区。

转储时路径命名以该时区时间为准。

state 否 String 转储状态。

● ACTIVE：表示进行转储。

● STOPPED：表示停止转储。

默认为STOPPED。

format 否 String 视频流转储格式。

● H264支持MP4和FLV

● H265只支持MP4 默认为FLV。

响应参数

状态码： 200

请求示例

PUT /v1/3266392d188c47d09948b1**********/streams/streamTest/retention { "store_type" : "obs",

"bucket" : "obs-momo", "path" : "path/**/video/***", "slice_in_minute" : 1, "timezone" : "GMT+8:00", "state" : "ACTIVE"

}

响应示例

状态码： 200

获取新上线设备列表_视频接入服务 VIS_API参考_设备指标统计_华为云

API 参考

目 录

1 使用前必读... 1

2 API 概览... 4

3 如何调用 API...7

4 服务开通管理...14

5 视频流管理...25

6 设备管理...52

7 凭证管理...73

8 设备指标统计...92

9 obs 桶策略管理... 126

10 公共数据结构... 131

11 附录... 133

A 修订记录... 140

1 使用前必读

1.1 概述

1.2 终端节点

1.3 约束与限制

1.4 基本概念

视频流

取流

拉流

转储

HTTP-FLV

设备

凭证

GB/T28181 密码

设备注册

视频邀约

HLS

2 API 概览

3 如何调用 API

3.1 构造请求

请求 URI

请求方法

请求消息头

请求消息体

username

domainname

********

cn-north-4

3.2 认证鉴权

Token 认证

AK/SK 认证

3.3 返回结果

状态码

响应消息头

响应消息体

4 服务开通管理

4.1 开通服务

功能介绍

接口约束

调试

URI

请求参数

响应参数

请求示例

响应示例

状态码

4.2 获取服务开通信息

功能介绍

接口约束

调试

URI

请求参数

响应参数

请求示例

响应示例

状态码

5 视频流管理

5.1 创建视频流

功能介绍

调试

URI

请求参数

响应参数

请求示例

响应示例

状态码

目录

1 ^{使用前必读}

2 ^{API 概览}

3 ^{如何调用 API}

4 ^{服务开通管理}

5 ^{视频流管理}