ROA 调用机制

概述

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

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

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

HTTP 请求结构

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

接口请求构造

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

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状态码为4xx或5xx，代表调用失败。

示例：

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

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

签名机制

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

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

/instances?group=test_group&status=ONLINE

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

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

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