运维编排服务HTTP调用方式有哪些？

本文适用基于API URL发起HTTP/HTTPS GET请求的用户，如果您使用的是SDK可以跳过此环节。

发起API请求的URL由不同参数拼凑而成，有固定的请求结构。URL中包含公共参数、您的签名机制和某个API的具体参数。每篇API文档均给出了URL请求示例供您参考，但是为了方便显示，我们并没有编码这些URL示例，您需要在发起请求前自行编码。我们根据您的签名验证了请求后，会返回结果。接口调用成功会显示返回参数，调用失败则显示相应报错，您可以根据公共错误码和具体API错误码分析排查。

公共参数分为公共请求参数和公共返回参数。

公共请求参数 名称 类型 是否必需 描述 Action String 是 API的名称。取值参见API概览。 AccessKeyId String 是 访问密钥ID。AccessKey用于调用API，而用户密码用于登录OOS 管理控制台 Signature String 是 您的签名。取值参见签名机制。 SignatureMethod String 是 签名方式。取值范围：HMAC-SHA1。 SignatureVersion String 是 签名算法版本。取值范围：1.0。 SignatureNonce String 是 签名唯一随机数。用于防止网络重放攻击，建议您每一次请求都使用不同的随机数。 Timestamp String 是 请求的时间戳。按照时间格式标准表示，并需要使用UTC时间，格式为yyyy-MM-ddTHH:mm:ssZ。示例：2019-06-01T12:00:00Z表示北京时间2019年06月01日12点00分00秒。 Version String 是 API 的版本号，格式为 YYYY-MM-DD。取值范围：2019-06-01。 Format String 是 返回参数的语言类型。取值范围：json。 请求示例 https://oos.cn-hangzhou.aliyuncs.com/?Action=XXXXXX &Format=json &Version=2019-06-01 &Signature=cWgxtKc9dQWgSMB7OEhtOkq%2B9AM%3D &SignatureMethod=HMAC-SHA1 &SignatureNonce=479a2bf5-8045-11e9-8d42-6c96cfdd1fa1 &SignatureVersion=1.0 &AccessKeyId=key-test &Timestamp=2019-05-27T06%3A04%3A25Z … 公共返回参数 名称 类型 描述 RequestId String 请求ID。无论调用接口成功与否，我们都会返回请求ID。

阿里云OOS API支持基于URL发起HTTP/HTTPS GET请求。请求参数需要包含在URL中。本文列举了GET请求中的结构解释，并提供了OOS的服务接入地址（Endpoint）。

结构示例 以下为CreateTemplate一条未编码的URL请求示例： https://oos.cn-hangzhou.aliyuncs.com/?Action=CreateTemplate &TemplateName=YourTemplateName &<公共请求参数> https指定了请求通信协议。 oos.cn-hangzhou.aliyuncs.com指定了OOS的服务接入地址（Endpoint）。 Action=CreateTemplate指定了要调用的API，TemplateName=YourTemplateName是CreateTemplate规定的参数。 <公共请求参数>是系统规定的公共参数。 通信协议 支持HTTP或HTTPS协议请求通信。为了获得更高的安全性，推荐您使用HTTPS协议发送请求。

涉及敏感数据时，如用户密码和SSH密钥对，推荐使用HTTPS协议。例如，在StartExecution中指定敏感参数时。

接入地址 OOS API的服务接入地址，参见以下表格。为较少网络延时，建议您根据业务调用来源配置接入地址。

华东1（杭州） oos.cn-hangzhou.aliyuncs.com 华北2（北京） oos.cn-beijing.aliyuncs.com 华北5（呼和浩特） oos.cn-huhehaote.aliyuncs.com 华北3（张家口) oos.cn-zhangjiakou.aliyuncs.com 中国香港 oos.cn-hongkong.aliyuncs.com 华东2（上海） oos.cn-shanghai.aliyuncs.com 华南1（深圳） oos.cn-shenzhen.aliyuncs.com 印度（孟买） oos.ap-south-1.aliyuncs.com 美国（弗吉尼亚） oos.us-east-1.aliyuncs.com 德国(法兰克福) oos.eu-central-1.aliyuncs.com 英国(伦敦) oos.eu-west-1.aliyuncs.com 请求参数 您需要通过Action参数指定目标操作，例如Action=CreateTemplate。还需要指定接口的其他参数以及公共请求参数。

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

对于每一次HTTP或者HTTPS协议请求，我们会根据访问中的签名信息验证访问请求者身份。具体由使用AccessKeyID和AccessKeySecret对称加密验证实现。

AccessKey相当于用户密码，AccessKey用于调用API，而用户密码用于登录OOS控制台。其中AccessKeyID是访问者身份，AccessKeySecret是加密签名字符串和服务器端验证签名字符串的密钥，必须严格保密谨防泄露。

说明 我们提供了多种编程语言的SDK及第三方SDK，可以免去您签名的烦恼。更多详情，请下载SDK。 构造规范化请求字符串 排序参数。排序规则以首字母顺序排序，排序参数包括公共请求参数和接口自定义参数，不包括公共请求参数中的Signature参数。 说明 当使用GET方法提交请求时，这些参数就是请求URL中的参数部分，即URL中?之后由&连接的部分。 编码参数。使用UTF-8字符集按照RFC3986规则编码请求参数和参数取值，编码规则如下： 字符A~Z、a~z、0~9以及字符 -、_、.、~不编码。 其它字符编码成%XY的格式，其中XY是字符对应ASCII码的16进制。示例：半角双引号（"）对应%22。 扩展的UTF-8字符，编码成%XY%ZA…的格式。 空格（ ）编码成%20，而不是加号（+）。该编码方式与application/x-www-form-urlencoded MIME格式编码算法相似，但又有所不同。如果您使用的是Java标准库中的java.net.URLEncoder，可以先用标准库中percentEncode编码，随后将编码后的字符中加号（+）替换为%20、星号（）替换为%2A、%7E替换为波浪号（~），即可得到上述规则描述的编码字符串。 private static final String ENCODING = "UTF-8"; private static String percentEncode(String value) throws UnsupportedEncodingException { return value != null ? URLEncoder.encode(value, ENCODING).replace("+", "%20").replace("", "%2A").replace("%7E", "~") : null; } 使用等号（=）连接编码后的请求参数和参数取值。 使用与号（&）连接编码后的请求参数，注意参数排序与步骤一：构造规范化请求字符串一致。 现在，您得到了规范化请求字符串（CanonicalizedQueryString），其结构遵循请求结构。

构造签名字符串 构造待签名字符串StringToSign。您可以同样使用percentEncode处理上一步构造的规范化请求字符串，规则如下： StringToSign= HTTPMethod + "&" + //HTTPMethod：发送请求的 HTTP 方法，例如 GET。 percentEncode("/") + "&" + //percentEncode("/")：字符（/）UTF-8 编码得到的值，即 %2F。 percentEncode(CanonicalizedQueryString) //您的规范化请求字符串。 按照RFC2104的定义，计算待签名字符串StringToSign的HMAC-SHA1值。示例使用的是Java Base64编码方法。 Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign) ) ) 添加根据RFC3986规则编码后的参数Signature到规范化请求字符串URL中。 说明 计算签名时，RFC2104规定的Key值是您的AccessKeySecret并加上与号（&)，其ASCII值为38。 示例 1. 参数拼接法 以调用ListTemplates查询模板为例。假设您获得了AccessKeyID=testid以及AccessKeySecret=testsecret，签名流程如下所示：

构造规范化请求字符串。 AccessKeyId=testid&Action=ListTemplates&Format=json&SignatureMethod=HMAC-SHA1&SignatureNonce=9a3fdf30-8049-11e9-8875-6c96cfdd1fa1&SignatureVersion=1.0&Timestamp=2019-05-27T06%3A35%3A22Z&Version=2019-06-01 构造待签名字符串StringToSign，详情请参见步骤二：构造签名字符串。 GET&%2F&AccessKeyId%3Dtestid&Action%3DListTemplates&Format%3Djson&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3D9a3fdf30-8049-11e9-8875-6c96cfdd1fa1&SignatureVersion%3D1.0&Timestamp%3D2019-05-27T06%253A35%253A22Z&Version%3D2019-06-01 计算签名值。因为AccessKeySecret=testsecret，用于计算的Key为testsecret&，计算得到的签名值为 1FcsD6/AvH2KugeowoCJSi8lBd8=。示例使用的是Java Base64编码方法。 Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign) ) ) 添加RFC3986规则编码后的Signature=1FcsD6%2FAvH2KugeowoCJSi8lBd8%3D到步骤一：构造规范化请求字符串的URL中。 http://oos.cn-hangzhou.aliyuncs.com/?SignatureVersion=1.0&Format=json&Timestamp=2019-05-27T06%3A35%3A22Z&AccessKeyId=testid&SignatureMethod=HMAC-SHA1&Version=2019-06-01&Signature=1FcsD6%2FAvH2KugeowoCJSi8lBd8%3D&Action=ListTemplates&SignatureNonce=9a3fdf30-8049-11e9-8875-6c96cfdd1fa1 通过以上URL，您可以使用浏览器、curl或者wget等工具发起HTTP请求调用ListTemplates，查询您的模板。

示例 2. 编程语言法 依然以调用ListTemplates查询模板为例。假设您获得了AccessKeyID=testid以及AccessKeySecret=testsecret，并且假定所有请求参数放在一个Java Map<String, String>对象里。

预定义编码方法。 private static final String ENCODING = "UTF-8"; private static String percentEncode(String value) throws UnsupportedEncodingException { return value != null ? URLEncoder.encode(value, ENCODING).replace("+", "%20").replace("*", "%2A").replace("%7E", "~") : null; } 预定义编码时间格式Timestamp。参数Timestamp必须符合时间格式规范，并需要使用UTC时间，时区为+0。 private static final String ISO8601_DATE_FORMAT = "yyyy-MM-dd'T'HH:mm:ss'Z'"; private static String formatIso8601Date(Date date) { SimpleDateFormat df = new SimpleDateFormat(ISO8601_DATE_FORMAT); df.setTimeZone(new SimpleTimeZone(0, "GMT")); return df.format(date); } 构造请求字符串。 final String HTTP_METHOD = "GET"; Map parameters = new HashMap(); // 输入请求参数 parameters.put("Action", "ListTemplates"); parameters.put("Version", "2019-06-01"); parameters.put("AccessKeyId", "testid"); parameters.put("Timestamp", formatIso8601Date(new Date())); parameters.put("SignatureMethod", "HMAC-SHA1"); parameters.put("SignatureVersion", "1.0"); parameters.put("SignatureNonce", UUID.randomUUID().toString()); parameters.put("Format", "JSON"); // 排序请求参数 String[] sortedKeys = parameters.keySet().toArray(new String[]{}); Arrays.sort(sortedKeys); final String SEPARATOR = "&"; // 构造 stringToSign 字符串 StringBuilder stringToSign = new StringBuilder(); stringToSign.append(HTTP_METHOD).append(SEPARATOR); stringToSign.append(percentEncode("/")).append(SEPARATOR); StringBuilder canonicalizedQueryString = new StringBuilder(); for(String key : sortedKeys) { // 这里注意编码 key 和 value canonicalizedQueryString.append("&") .append(percentEncode(key)).append("=") .append(percentEncode(parameters.get(key))); } // 这里注意编码 canonicalizedQueryString stringToSign.append(percentEncode( canonicalizedQueryString.toString().substring(1))); 签名。因为 AccessKeySecret=testsecret，所以用于计算HMAC的Key为testsecret&，计算得到的签名值为1FcsD6/AvH2KugeowoCJSi8lBd8=。 // 以下是一段计算签名的示例代码 final String ALGORITHM = "HmacSHA1"; final String ENCODING = "UTF-8"; key = "testsecret&"; Mac mac = Mac.getInstance(ALGORITHM); mac.init(new SecretKeySpec(key.getBytes(ENCODING), ALGORITHM)); byte[] signData = mac.doFinal(stringToSign.getBytes(ENCODING)); String signature = new String(Base64.encodeBase64(signData)); 增加签名参数后，按照RFC3986规则编码后的URL如下所示： http://oos.cn-hangzhou.aliyuncs.com/?SignatureVersion=1.0&Format=json&Timestamp=2019-05-27T06%3A35%3A22Z&AccessKeyId=testid&SignatureMethod=HMAC-SHA1&Version=2019-06-01&Signature=1FcsD6%2FAvH2KugeowoCJSi8lBd8%3D&Action=ListTemplates&SignatureNonce=9a3fdf30-8049-11e9-8875-6c96cfdd1fa1

使用浏览器、curl或者wget等工具发送HTTP请求。 { "Templates": [ { "Hash": "9ea05673ea6c7d03fe8707ddd3d347d74f9e47963538097d120583c0b5385edf", "Description": "", "TemplateName": "demo", "ShareType": "Private", "Tags": [], "TemplateFormat": "JSON", "CreatedBy": "1000008528360000", "CreatedDate": "2019-06-01T12:00:00Z", "TemplateVersion": "v1", "TotalExecutionCount": 1 },...], "NextToken": "gAAAAABc5pnvl_meBuZkGEbZNmzTOA1RotEjFs4q8q2fICes_oGk4qenxGB5UeyXYWa5eF4TeZLQMpnVc6rmhr2BC0Kahyx1P5brt_fQvLFTLBEcXQzzqsWwxDS-Y1xL7pkhOOgU_K3Z0-dMQHOkIQwWhodp4qutzKNO7gQ-EPWQvM1ugrGkonFDe_bV3TckHyHqgJDTLwk8Swfm1NvnZTXg9AH8YLvhu0fTK8sgXI6nBkvqTkozedWFhq8jmH1SFbs1yVZoKoKpFaYV6-vuTFcUO9G9-5W0YVdfliTuEOf42QHtkWLZ8jj1Xhmk9rTBYjb7P4KmRm7b7UhQ6FamvpVv9vXlCQvWAafnPgT98ViFlr6z7ByNHrI=", "RequestId": "8B813042-7F00-45CE-AF8C-85CCEEFC6BA2", "MaxResults": 50 } 返回结果列举了模板信息。

返回结果为JSON格式。为了便于查看和美观，API文档返回示例均有换行和缩进等处理，实际返回结果无换行和缩进处理。

正常返回示例 接口调用成功后会返回接口返回参数和请求ID，我们称这样的返回为正常返回。HTTP状态码为2xx。

JSON示例

{ "RequestId": "AC467B38-3910-447D-87BC-AC049166F216" /* 返回结果数据 */ } 异常返回示例 接口调用出错后，会返回错误码、错误信息和请求ID，我们称这样的返回为异常返回。HTTP状态码为4xx或者5xx。

您可以根据接口错误码，参考公共错误码以及API错误中心排查错误。当您无法排查错误时，可以提交工单联系我们，并在工单中注明服务节点HostId和RequestId。

JSON示例

{ "RequestId": "A40CFF28-407A-40B5-B6A5-AC049166F216", /* 请求 ID / "HostId": "oos.cn-hangzhou.aliyuncs.com", / 服务节点 / "Code": "InvalidNextToken", / 错误码 / "Message": "NextToken is invalid" / 错误信息 / } 公共错误码 错误代码 HTTP状态码 错误信息 描述 InvalidVersion 400 Specified parameter Version is not valid. 给定的Version非法。请检查URL中指定的Version的正确性。 InvalidAction.NotFound 400 Specified api is not found, please check your url and method. 给定的API不存在。请检查URL中指定的Action的正确性。 Throttling.User 400 Request was denied due to user flow control. 访问频率太高导致流控。 InvalidParameter 400 内容随校验场景不同而不同，如 TemplateName can not contain “” 参数非法。请根据错误信息来检查指定参数的正确性。 User.NoPermission 400 User has no permission to do the action: ({api_name}) 用户没有调用某个API的权限。请检查是否在RAM中给当前用户赋予了OOS的API的权限。 InvalidStsToken 400 Invalid STS token to do the action: ({api_name}) 给定的STS Token非法。 ExpiredStsToken 400 Expired STS token to do the action: ({api_name}) 给定的STS Token过期。 MissingParameter 400 The Parameter ({name}) was not provided. 缺少必填参数。 QuotaExceed 400 The Quota ({key}) exceeded ({value}). 特定属性（如模板数量、正在运行的执行数等）超过上限。 InvalidAccountType 400 The account type ({account_type}) was not supported. 不支持给定的账号类型。 TemplateValidationError 400 {reason} 模板约束，如参数类型、数值等，校验不通过。 InvalidFunctionParameters 400 The specified function {fn_name}’s parameters are incorrect. 模板中使用函数时给定的参数校验错误。请检查参数的数量和值。 InvalidTemplateReference 400 The specified reference {resource} (in {key}) is incorrect. 模板内参数引用不正确。 UnknownUserParameter 400 The parameter ({key}) was not defined in engine. 模板中给定的参数未定义或不被支持。 InvalidTimerTriggerParameter 400 The parameter ({key}) is invalid TimerTrigger动作的给定参数非法。 InvalidTemplateParameter 400 The parameter ({key}) has no attributes. 模板中的Parameters类型非法，必须为字典。