首页 阿里云SDK 调用机制 ROA 调用机制

ROA 调用机制

ROA 调用机制介绍。

概述

本文介绍了阿里云 OpenAPI 的 ROA 调用风格。如果您想要自研阿里云 ROA 调用风格的 OpenAPI SDK,请参看此文,请务必先参看[阿里云开放 API 自研 SDK 开发指南]。如果您可以使用官方 SDK,请参看 [阿里云开放 API 官方 SDK 开发指南]。

阿里云 ROA OpenAPI 向开发者提供HTTP接口,您可以参看如下文档,来构造 HTTP 接口以调用对应的 OpenAPI 。

本文将介绍 ROA OpenAPI 请求的组成部分,然后介绍如何通过这些组成部分构造一个 OpenAPI 请求,以及如何获取返回结果。

HTTP 请求结构

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

名称

是否必选

描述

示例值

协议

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

https://

服务地址

即 Endpoint。您可以查阅不同云产品的服务接入地址文档,查阅不同服务区域下的服务地址。更多信息,请查看[阿里云OpenAPI服务地址介绍]

cs.aliyuncs.com

resource_URI_parameters

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

/k8s/ClusterId/external/agent/deployment?PrivateIpAddress=String

RequestHeader

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

RequestBody

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

HTTPMethod

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

GET

RequestHeader(请求头)

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

名称

类型

是否必选

描述

示例值

x-acs-action

String

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

GetInstance

x-acs-version

String

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

2018-12-01

Accept

String

指定接口返回数据的格式。ROA 只支持固定值 application/json

application/json

Authorization

String

非匿名请求必须

用于验证请求合法性的认证信息,格式为AccessKeyId:Signature。其中AccessKeyId 为用户的访问密钥ID。您可以在RAM 控制台 查看您的 AccessKeyId。如需创建 AccessKey,请参见创建 AccessKey

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

***

x-acs-signature-nonce

String

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

15215528852396

Date

String

HTTP 1.1协议中规定的 GMT 时间,例如:Tue 9 Apr 2019 07:35:29 GMT

Tue 9 Apr 2019 07:35:29 GMT

x-acs-signature-method

String

非匿名请求必须

签名方式。目前为固定值 HMAC-SHA1

HMAC-SHA1

Content-MD5

String

HTTP请求正文的128-bit MD5散列值转换成BASE64编码的结果

Host

String

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

cs.aliyuncs.com

接口请求构造

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

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 请求结构

示例:

POST /clusters/cluster_id/attach HTTP/1.1
<公共请求头>
{
    "password": "Hello1234",
    "instances": [
        "i-xxxx",
        "i-yyyy"
    ]
}

请求编码

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

接口返回结果

每次接口调用请求,无论成功与否,系统都会返回一个唯一识别码RequestId。调用API服务后返回数据采用统一格式。返回的HTTP状态码为2xx,代表调用成功;返回的HTTP状态码为4xx5xx,代表调用失败。

示例:

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

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

签名机制

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

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

步骤一:构造规范化请求头

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

  • 将所有以x-acs-为前缀的HTTP请求头的名称转换成小写字母。如X-acs-Meta-Name: TaoBao转换成

    x-acs-meta-name: TaoBao。阿里云规范请求头的名称大小写不敏感,建议全小写。

  • 如果一个公共请求头的值过长,则需要处理其中的\t\n\r\f分隔符,将其替换成英文半角的空格。

  • 将上一步得到的所有HTTP阿里云规范头按照字典顺序进行升序排列。

  • 删除请求头的名称和值之间的分隔符两端出现的任何空格。例如x-acs-oss-meta-name :TaoBao,Alipay转换成x-acs-oss-meta-name:TaoBao,Alipay

  • 在每一个请求头后添加一个\n分隔符(包括最后一个请求头),然后将所有请求头拼接在一起即获得CanonicalizedHeaders。

步骤二:构造规范化资源

规范化资源(CanonicalizedResource) 表示您想要访问资源的规范描述,具体构造方式如下:

  1. 将请求的查询字符串(queryString)中的参数按照参数名称的字典序重新排序,并以&分隔符连接生成已排序查询字符串。

  2. 将请求资源路径(指URL中host与查询字符串之间的部分,包含host之后的/但不包含查询字符串前的?)与已排序查询字符串以?拼接,得到规范化资源。当查询字符串不存在时,直接用请求资源路径作为规范化资源。

示例

原始请求URL:

http://demo-product.aliyuncs.com/instances?status=ONLINE&group=test_group

规范化资源:

/instances?group=test_group&status=ONLINE

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

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

String stringToSign = 
    HTTPMethod + "\n" +
    Accept + "\n" +
    ContentMD5 + "\n" +
    ContentType + "\n" +
    Date + "\n" +
    CanonicalizedHeaders +
    CanonicalizedResource

参数

描述

HTTPMethod

大写的HTTP方法名,例如POST、GET。

Accept

Accept请求头的值,当请求头不存在时,使用空字符串代替。

ContentMD5

Content-MD5请求头的值,当请求头不存在时,使用空字符串代替。

ContentType

Content-Type请求头的值,当请求头不存在时,使用空字符串代替。

Date

Date请求头的值。

CanonicalizedHeaders

步骤一:构造规范化请求头中获得的规范化请求头。

CanonicalizedResource

步骤二:构造规范化资源中获得的规范化资源。

步骤四:计算签名

根据RFC2104的定义,按照HMAC-SHA1算法对上一步生成的待签名字符串进行签名计算,并以Base64编码规则将计算结果编码成字符串,即得到最终的签名值(signature)。

String signature = Base64(HMAC_SHA1(SigningKey, stringToSign))
重要

计算签名时使用的SigningKey值就是您的AccessKey Secret。更多信息,请参见创建AccessKey

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

计算出签名结果 signature后,按照以下规则拼接字符串,并将结果作为 Authorization 请求头的值。

String Authorization = "acs " + AccessKeyId + ":" + signature

阿里云首页 阿里云SDK 相关技术圈