文档

V3版本请求体&签名机制

更新时间:
一键部署

V3版本通过公共请求头设置接口必要的参数信息,在签名机制的实现上屏蔽了接口风格的差异,更标准、更简单。本文提供了详细的指南,用于帮助您了解和实施阿里云SDK V3版的请求结构和签名过程。您会了解到如何构造标准的HTTP请求,以及如何使用正确的签名算法来验证请求的身份,确保传输的数据的完整性和安全性。如果您想要自研阿里云的 OpenAPI SDK,您可以参看本文。

HTTP 请求结构

一个完整的阿里云 OpenAPI 请求,包含以下部分。

名称

是否必选

描述

示例值

协议

您可以查阅不同云产品的 API 参考文档进行配置。支持通过HTTPHTTPS协议进行请求通信。为了获得更高的安全性,推荐您使用HTTPS协议发送请求。取值范围为https://或者 http://

https://

服务地址

即 Endpoint。您可以查阅不同云产品的服务接入地址文档,查阅不同服务区域下的服务地址。

cs.aliyuncs.com

resource_URI_parameters

接口URL,包括接口路径和位置在 path、 query的接口请求参数。

/clusters/{cluster_id}/triggers

RequestHeader

请求头信息,通常包含API的版本、Host、Authorization等信息。后文将详细说明。

x-acs-action

RequestBody

定义在 body 中的业务请求参数,建议您在阿里云 OpenAPI 开发者门户进行试用。

cluster_id

HTTPMethod

请求使用的方法,ROA接口请求方法包括PUT、POST、GET、DELETE。

POST

RequestHeader(公共请求头)

一个完整的阿里云 OpenAPI 请求,包含以下部分。

名称

类型

是否必选

描述

示例值

x-acs-action

String

API的名称。您可以访问阿里云 OpenAPI 开发者门户,搜索您想调用的 OpenAPI

CreateTrigger

x-acs-version

String

API 版本。您可以访问阿里云 OpenAPI 开发者门户,查看您调用 OpenAPI 对应的 API 版本

2015-12-15

Authorization

String

非匿名请求必须

用于验证请求合法性的认证信息,格式为Authorization: SignatureAlgorithm Credential=AccessKeyId,SignedHeaders=SignedHeaders,Signature=Signature。其中SignatureAlgorithm为签名加密方式,为ACS3-HMAC-SHA256。

Credential 为用户的访问密钥ID。您可以在RAM 控制台查看您的 AccessKeyId。如需创建 AccessKey,请参见创建AccessKeySignedHeaders为请求头中包含的参与签名字段键名,【说明】:除Authorization外的所有公共请求头,只要存在必须被加入签名。

Signature为请求签名,取值参见签名机制。

ACS3-HMAC-SHA256 Credential=YourAccessKeyId,SignedHeaders=content-type;host;x-acs-timestamp,Signature=6b595d672d79c15b18edb4ccfba6789a24a6f2b82c400e03162d9279b08555d7

x-acs-signature-nonce

String

签名唯一随机数。用于防止网络重放攻击,建议您每一次请求都使用不同的随机数。

15215528852396

x-acs-date

String

按照ISO 8601标准表示的UTC时间,格式为yyyy-MM-ddTHH:mm:ssZ,例如2018-01-01T12:00:00Z。值为请求发出前15分钟内的时间。

2018-01-01T12:00:00Z

host

String

即服务地址,参见HTTP 请求结构

cs.aliyuncs.com

x-acs-content-sha256

String

请求正文Hash摘要后再base-16编码的结果,与HashedRequestPayload一致。

x-acs-security-token

String

STS认证必传

为调用Assumerole接口返回值中SecurityToken的值。

接口请求构造

一个完整的接口请求构造如下:

HTTPMethod /resource_URI_parameters
RequestHeader
RequestBody

请求参数由公共请求头和API自定义参数组成。公共请求头中包含API版本号、身份验证等信息。

  • HTTPMethod :请求使用的方法,包括PUT、POST、GET、DELETE。详情请参看HTTP 请求结构

  • resource_URI_parameters:请求要调用的资源标识符,如/cluster。详情请参看HTTP 请求结构

  • RequestHeader:请求头信息,通常包含API的版本、Host、Authorization等信息。详情请参看HTTP 请求结构

  • RequestBody:在 body 中的业务请求参数。详情请参看HTTP 请求结构

请求RunInstances接口示例:

POST /?ImageId=win2019_1809_x64_dtc_zh-cn_40G_alibase_20230811.vhd&RegionId=cn-shanghai HTTP/1.1
Authorization: ACS3-HMAC-SHA256 Credential=YourAccessKeyId,SignedHeaders=host;x-acs-action;x-acs-content-sha256;x-acs-date;x-acs-signature-nonce;x-acs-version,Signature=e521358f7776c97df52e6b2891a8bc73026794a071b50c3323388c4e0df64804
x-acs-action: RunInstances
host: ecs.cn-shanghai.aliyuncs.com
x-acs-date: 2023-10-26T09:01:01Z
x-acs-version: 2014-05-26
x-acs-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-acs-signature-nonce: d410180a5abf7fe235dd9b74aca91fc0
user-agent: AlibabaCloud (Mac OS X; x86_64) Java/1.8.0_352-b08 tea-util/0.2.6 TeaDSL/1
accept: application/json

请求编码

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

接口返回结果

每次接口调用请求,无论成功与否,系统都会返回一个唯一识别码RequestId。调用API服务后返回数据采用统一格式。接口调用成功后,会返回接口的返回参数请求 ID,HTTP 状态码为 2xx(不显示在响应正文中)。响应正文示例如下:

{
    "RequestId": "4C467B38-3910-447D-87BC-AC049166F216"/* 返回结果数据 */
}

接口调用出错后,会返回请求ID、服务节点、错误码和错误信息,HTTP 状态码为 4xx 或者 5xx。示例如下:

{
    "code": "400", /* 错误码 */
    "message": "Cluster permission denied", /* 错误信息 */
    "requestId": "A026BC61-0523-5A6D-A5F3-314A3D92FD50", /* 请求 ID */
    "status": 400 /* 业务字段 */
}

接口调用出错后,您可以根据返回的RequestId,在阿里云OpenAPI开发者门户-诊断中排查。此外,您还可以查阅公共错误码以及API 错误中心。当您无法排查错误时,可以提交工单,并在工单中注明Host(服务地址,参见HTTP 请求结构)和RequestId

签名机制

为保证API的安全调用,在调用API时阿里云会对每个API请求通过签名(Signature)进行身份验证。无论使用HTTP还是HTTPS协议提交请求,都需要在请求中包含签名信息。本文指导您如何进行签名处理。

对于每一次HTTP或者HTTPS协议请求,阿里云会根据访问中的签名信息验证访问请求者身份。您在访问时签名信息时,请按照以下方法对请求进行签名处理:

步骤一:构造规范化请求

使用AK/SK方式进行签名与认证,首先需要规范请求内容,然后再进行签名。客户端与云服务API网关使用相同的请求规范,可以确保同一个HTTP请求的前后端得到相同的签名结果,从而完成身份校验。

构造规范化请求(CanonicalRequest)的伪代码如下:

CanonicalRequest =
  HTTPRequestMethod + '\n' +    //http方法名,全大写
  CanonicalURI + '\n' +         //规范化URI
  CanonicalQueryString + '\n' + //规范化查询字符串
  CanonicalHeaders + '\n' +     //规范化消息头
  SignedHeaders + '\n' +        //已签名消息头
  HashedRequestPayload			
  • 请求方法(HTTPRequestMethod)即大写的http方法名,如GET、POST。

  • 规范化URI(CanonicalURI)

    即URL的资源路径部分经过编码得到,资源路径部分指URL中host与查询字符串之间的部分,包含host之后的/但不包含查询字符串前的?。用户发起请求时的URI应使用规范化URI,编码方式使用UTF-8字符集按照RFC3986的规则对URI中的每一部分(即被/分割开的字符串)进行编码:

    • 字符A~Z、a~z、0~9以及字符-_.~不编码。

    • 其他字符编码成%XY的格式,其中XY是字符对应ASCII码的16进制。示例:半角双引号(")对应%22

    • 扩展的UTF-8字符,编码成%XY%ZA…的格式。

    • 空格( )编码成%20,而不是加号(+)。该编码方式与application/x-www-form-urlencodedMIME格式编码算法相似,但又有所不同。

      如果您使用的是Java标准库中的java.net.URLEncoder,可以先用标准库中percentEncode编码,随后将编码后的字符中加号(+)替换为%20、星号(*)替换为%2A%7E替换为波浪号(~),即可得到上述规则描述的编码字符串

    【注意】:当资源路径为空时,使用正斜杠(/)作为CanonicalURI。

  • 规范化查询字符串(CanonicalQueryString)构造方法如下:

    • 将查询字符串中的参数按照参数名的字符代码升序排列,具有重复名称的参数应按值进行排序。

    • 使用UTF-8字符集按照RFC3986的规则对每个参数的参数名和参数值分别进行URI编码,具体规则与上一节中CanonicalURI的编码规则相同。

    • 使用等号(=)连接编码后的请求参数名和参数值,对于没有值的参数使用空字符串。

    • 将请求参数按编码后的参数名的字符代码顺序以升序排列,具有相同名称的参数按编码后的参数值进行排序。

    • 按照步骤4中的顺序使用与号(&)连接编码后的请求参数。

    【注意】:当请求的查询字符串为空时,使用空字符串作为规范化查询字符串,实际上就是空白行

  • 规范化请求头(CanonicalizedHeaders)是非标准HTTP头部信息。是指请求中出现的以x-acs-为前缀的参数信息,构造方法如下:

    • 将所有需要签名的消息头的名称转换为小写。

    • 将消息头的值除去首尾空格。对于有多个值的消息头,将多个值分别除去首尾空格后按值升序排列,然后用逗号(,)连接。

    • 将步骤1、2的结果以英文冒号(:)连接,并在尾部添加换行符,组成一个规范化消息头(CanonicalHeaderEntry)。

    • 多个规范化消息头,按照消息头名称(小写)的字符代码顺序以升序排列后拼接在一起。

    • 如果没有需要签名的消息头,使用空字符串作为规范化消息头列表。

【说明】:除Authorization外的所有公共请求头,只要存在必须被加入签名。

  • 已签名消息头列表(SignedHeaders)用于说明此次请求有哪些消息头参与了签名,与CanonicalHeaders中包含的消息头是一一对应的,构造方法如下:

    • 将CanonicalHeaders中包含的请求头的名称转为小写

    • 多个请求头名称(小写)按首字母升序排列并以英文分号(;)分隔,例如 content-type;host;x-acs-date

    • 伪代码如下:

      CanonicalHeaderEntry = Lowercase(HeaderName) + ':' + Trim(HeaderValue) + '\n'
      
      CanonicalHeaders = 
          CanonicalHeaderEntry0 + CanonicalHeaderEntry1 + ... + CanonicalHeaderEntryN
  • 使用哈希函数对请求正文(RequestPayload)转换的值(HashedRequestPayload),转换规则用伪代码可表示为 HashedRequestPayload = HexEncode(Hash(RequestPayload))

    • Hash表示消息摘要函数,目前支持SHA256算法,例如,当签名协议使用ACS3-HMAC-SHA256时,应使用SHA256作为Hash函数。

    • HexEncode表示以小写的十六进制的形式返回摘要的编码函数(即Base16编码)

    • 【注意】当请求正文为空时,比如GET请求,RequestPayload固定为空字符串

    表1:签名协议与签名算法、摘要函数的对应关系

    签名协议(SignatureAlgorithm)

    处理RequestPayload以及CanonicalRequest时使用的摘要函数(Hash)

    计算签名时实际使用的签名算法

    (SignatureMethod)

    ACS3-HMAC-SHA256

    SHA256

    HMAC-SHA256

步骤二:构造待签名字符串

按照以下伪代码构造待签名字符串(stringToSign):

StringToSign =
    SignatureAlgorithm + '\n' +
    HashedCanonicalRequest
  • SignatureAlgorithm

    签名协议,目前支持ACS3-HMAC-SHA256,不再支持基于MD5或SHA1的算法。

  • HashedCanonicalRequest

    规范化请求摘要串,计算方法伪代码如下:

    HashedCanonicalRequest = HexEncode(Hash(CanonicalRequest))
  1. 使用哈希函数(Hash)对步骤一中得到的规范化请求(CanonicalRequest)进行摘要处理,具体使用的Hash函数取决于签名协议(SignatureAlgorithm),参见表1,例如,当签名协议为ACS3-HMAC-SHA256时,应使用SHA256作为Hash函数。

  2. 将上一步得到的摘要结果以小写的十六进制形式编码。

步骤三:计算签名

按照以下伪代码计算签名值(Signature)。

Signature = HexEncode(SignatureMethod(Secret, StringToSign))

  • StringToSign:步骤二中构造的待签名字符串,UTF-8编码。

  • SignatureMethod:签名算法,具体使用的算法取决于签名协议(SignatureAlgorithm),其对应关系如表1。

  • Secret:用户的签名密钥,为二进制数据。

  • HexEncode:以小写的十六进制的形式返回摘要的编码函数(即Base16编码)。

步骤四:将签名添加到请求中

计算完签名后,构造Authorization请求头,格式为:Authorization:<SignatureAlgorithm> Credential=<AccessKeyId>,SignedHeaders=<SignedHeaders>,Signature=<Signature>示例如下:

Authorization:ACS3-HMAC-SHA256 Credential=YourAccessKeyId,SignedHeaders=content-type;host;x-acs-timestamp,Signature=6b595d672d79c15b18edb4ccfba6789a24a6f2b82c400e03162d9279b08555d7

签名示例

本示例以调用云服务器 ECS RunInstances为例。假设您获得了AccessKeyID 为 YourAccessKeyId

, AccessKeySecret 为 YourAccessKeySecret,x-acs-signature-nonce 为 3156853299f313e23d1673dc12e1703d,接口请求时间为 2023-10-26T10:22:32Z。签名流程如下:

  1. 构造规范化请求。

POST
/
ImageId=win2019_1809_x64_dtc_zh-cn_40G_alibase_20230811.vhd&RegionId=cn-shanghai
host:ecs.cn-shanghai.aliyuncs.com
x-acs-action:RunInstances
x-acs-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-acs-date:2023-10-26T10:22:32Z
x-acs-signature-nonce:3156853299f313e23d1673dc12e1703d
x-acs-version:2014-05-26

host;x-acs-action;x-acs-content-sha256;x-acs-date;x-acs-signature-nonce;x-acs-version
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
  1. 构造待签名字符串。

ACS3-HMAC-SHA256
7ea06492da5221eba5297e897ce16e55f964061054b7695beedaac1145b1e259
  1. 计算签名。

06563a9e1b43f5dfe96b81484da74bceab24a1d853912eee15083a6f0f3283c0
  1. 将签名添加到请求中。

POST /?ImageId=win2019_1809_x64_dtc_zh-cn_40G_alibase_20230811.vhd&RegionId=cn-shanghai HTTP/1.1
Authorization: ACS3-HMAC-SHA256 Credential=YourAccessKeyId,SignedHeaders=host;x-acs-action;x-acs-content-sha256;x-acs-date;x-acs-signature-nonce;x-acs-version,Signature=e521358f7776c97df52e6b2891a8bc73026794a071b50c3323388c4e0df64804
x-acs-action: RunInstances
host: ecs.cn-shanghai.aliyuncs.com
x-acs-date: 2023-10-26T09:01:01Z
x-acs-version: 2014-05-26
x-acs-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-acs-signature-nonce: d410180a5abf7fe235dd9b74aca91fc0
user-agent: AlibabaCloud (Mac OS X; x86_64) Java/1.8.0_352-b08 tea-util/0.2.6 TeaDSL/1
accept: application/json
  • 本页导读 (1)
文档反馈