CDN加速

调用方式

更新时间:2021-06-03 16:26:07

企业直播OpenAPI调用方法

目录

一、请求结构

客户调用openAPI接口,是通过向指定服务地址发送请求,并需满足签名信息和具体接口的业务信息来完成的。openAPI的请求结构组织如下:

服务地址

我们的服务在全球多个Region部署,每个Region有自己对应的API域名、存储服务、直播服务,不可跨区域使用。

aws4_request 英文缩写 API域名 备注
华北Region cn-north-1 api.elive.wangsu.com 已上线
美东Region us-east-1 待开放
新加坡Region ap-singapore-1 待开放
法兰克福Region eu-frankfurt-1 待开放

通信协议

支持通过 HTTP 或 HTTPS 两种方式进行请求通信,推荐使用安全性更高的 HTTPS方式发送请求。
请求方法
请求方法详见各个接口具体的需求。在平台中的openAPI大多数支持Get或Post请求。

  1. 注意:
  2.  1.Get与Post请求都支持将公共信息放置在header中的模式。
    
  3.  2.Get请求还支持将公共信息放置在query string中的模式。
    

请求参数

openAPI请求包含两类参数:公共请求参数和接口请求参数。其中,公共请求参数是每一个接口需要包含的,具体可参见公共参数小节。接口请求参数是各个接口特有的,详见各个接口描述。

字符编码

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

二、公共参数

公共请求参数是每个接口都需要使用的请求参数,开发者每次使用OpenAPI发送请求时都需要携带这些公共请求参数,否则会导致请求失败。公共请求参数首字母均为大写,以此区分接口请求参数。

公共参数如下表

字段名 类型 是否必填 在query string中是否参与签名 参数格式 描述
Action string [a-zA-Z]+ 接口的名字,与具体的接口相关。
Version string YYYY-MM-DD 接口的版本信息
X-Amz-Algorithm string AWS4-HMAC-SHA256 目前平台仅支持HMAC-SHA256的签名算法
X-Amz-Credential string AccessKeyId /YYYYMMDD/region /service/AWS4_request 签名信任信息,包括密钥ID,日期,region,服务名已经尾部结构。
X-Amz-Date string ISO 8601 基本格式YYYYMMDD’T’HHMMSS’Z’,如20151101T120000Z 签名的日期
X-Amz-Signature string 16进制编码表示 签名的结果
X-Amz-SignedHeaders string [a-zA-Z0-9-;]+ 参与签名的header信息
X-Amz-Expires integer [0-9]+ 签名的有效时间范围。单位是秒

注意:所以的公共参数支持放置在query string当中。在签名信息放置在header中的模式里还支持将X-Amz-Date与X-Amz-Expires放置在header中,并且将X-Amz-Algorithm、X-Amz-Credential、X-Amz-SignedHeaders、X-Amz-Signature信息放置在authorization的header中。其中authorization的结构如下:^([a-zA-Z0-9-]{1,16}).Credential=([a-zA-Z0-9-/]+),.SignedHeaders=([a-zA-Z0-9-;]+),.Signature=([a-zA-Z0-9-_]+)

切记两种签名模式不能混用,否则会造成签名不通过的情况发生。

三、签名机制

我们的openapi签名机制兼容AWS的签名算法V4版本,并同时支持Get、Post两种HttpMethod。对于Get、Post两种方式都可以将签名的信息放在名为authorization的header当中,对于Get方式的请求另外支持将签名信息存放在query string中的模式。下文将分别描述两种签名的模式。

3.1 签名信息存放在header中的签名模式

  1. 创建一个正规化请求
    在签名之前,首先要将请求正规化,目的是让签名计算过程无异议,其主要过程及伪代码如下:
  2. CanonicalRequest = HTTPRequestMethod + ‘\n’ + CanonicalURI + ‘\n’ + CanonicalQueryString + ‘\n’ + CanonicalHeaders + ‘\n’ + SignedHeaders + ‘\n’ + HexEncode(Hash(RequestPayload))
    Hash指代SHA-256,HexEncode指代转16进制编码(使用小写字母)。
    HTTPRequestMethod:
    指代http请求的method,例如:GET、POST等。
    CanonicalURI:
    指代正规化后的URI。如果URI为空,那么使用"/“作为绝对路径。在视频平台中绝大多数接口的URI都为”/"。
    CanonicalQueryString:
    指代正规化后的Query String。对于Query String的正规化大致的过程如下:
    • URI编码每一个querystring参数名称和参数值。
    • 按照ASCII字节顺序对参数名称严格排序。
    • 将排序好的参数名称和参数值用=连接,按照排序结果将“参数对”用&连接。
    • 例如:
  3. CanonicalQueryString = “Action=GetPlayInfo&Version=2019-03-15”
    CanonicalHeaders:
    指代正规化后的Header。其中伪代码如下:
  4. CanonicalHeaders = CanonicalHeadersEntry0 + CanonicalHeadersEntry1 + … + CanonicalHeadersEntryN
    其中:
  5. CanonicalHeadersEntry = Lowercase(HeaderName) + ‘:’ + Trimall(HeaderValue) + ‘\n’
    Lowcase代表将Header的名称全部转化成小写,Trimall表示去掉Header的值的前后多余的空格。
    特别注意:最后需要添加"\n"的换行符。
    SignedHeaders:
    代指参与签名的header名称。签名header是包含在正规化headers中名称列表,其目的是指明哪些header参与签名计算,从而忽略请求被proxy添加的额外header,其中host、x-amz-date两个header如果存在则必须添加进来,伪代码如下:
  6. SignedHeaders = Lowercase(HeaderName0) + ‘;’ + Lowercase(HeaderName1) + “;” + … + Lowercase(HeaderNameN)
    RequestPayload:
    指代完整的请求的body。
  • URI编码(注:同RFC3986方法)每一个querystring参数名称和参数值(注:GET方式需要包含哈希算法、信任状、签名日期和签名header等全部参数)。
  • 按照ASCII字节顺序对参数名称严格排序。
  • 将排序好的参数名称和参数值用=连接,按照排序结果将“参数对”用&连接。

2.创建签名字符串
签名字符串主要包含请求以及正规化请求的元数据信息,由签名算法、请求日期、信任状和正规化请求哈希值连接组成,伪代码如下:

  1. StringToSign = Algorithm + ‘\n’ + RequestDate + ‘\n’ + CredentialScope + ‘\n’ + HexEncode(Hash(CanonicalRequest))
    Algorithm
    指代签名的算法,目前视频平台仅支持AWS4-HMAC-SHA256的签名算法。
    RequestDate
    指代请求UTC时间,请使用如下格式:YYYYMMDD’T’HHMMSS’Z’ 。
    CredentialScope
    指代签名中的信任范围,格式为:YYYYMMDD/region/service/aws4_request。
    Credential
    指代信任状,格式为:AccessKeyId/YYYYMMDD/region/service/aws4_request。
    CanonicalRequest
    指代上一小节正规化请求的结果。

3.计算签名秘钥
在计算签名前,首先从私有访问密钥(secret AccessKey)派生出签名密钥(signing key),而不是直接使用私有访问密钥。具体计算过程如下:

  1. kSecret = Your KSC Secret Access Key
  2. kDate = HMAC(“AWS4” + kSecret, Date)
  3. kRegion = HMAC(kDate, Region)
  4. kService = HMAC(kRegion, Service)
  5. kSigning = HMAC(kService, “aws4_request”)
    说明:关于私有访问密钥(secret AccessKey)的获取,当前请联系网宿客服人员获取。

计算签名
最终计算出的Signature信息。

  1. Signature = HexEncode(HMAC(kSigning, StringToSign))
    构建签名header
    在完成以上步骤以后,签名的绝大多数的过程已经完成。接下来需要把签名的信息放置在Authorization的header当中。其中的组织架构大致如下:
  2. AWS4-HMAC-SHA256 Credential={Credential}, SignedHeaders={SignedHeaders}, Signature={Signature}
    表达式中用{}括起来的代表上文计算出的中间过程。

3.2 签名信息存放在query string中的签名模式

将签名信息存放在query string中的签名模式的前4部与放置在header中的过程完全相同。只是最后一步稍有不同。

  1. 构建签名query
    将签名的信息以query的方式填写到如下字段中:
    X-Amz-Algorithm:
    指代签名的算法,目前视频平台只支持AWS4-HMAC-SHA256。
    X-Amz-Credential
    指代签名的信任状。
    X-Amz-Date
    指代签名的时间。
    X-Amz-SignedHeaders
    指代参与签名的Header的信息。
    X-Amz-Signature
    指代签名的结果。
    X-Amz-Expires
    指代请求的超时时间,可空缺。
    注意:虽然X-Amz-Signature这个字段在Query String中,但是此字段不参与签名