全部产品
弹性计算 会员服务 网络 安全 移动云 数加·大数据分析及展现 数加·大数据应用 管理与监控 云通信 阿里云办公 培训与认证 更多
存储与CDN 数据库 域名与网站(万网) 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 智能硬件
专有网络 VPC

调用专用网络API

更新时间:2018-04-04 19:11:50

对 VPC 服务接口的调用是通过向VPC服务端发送HTTP请求(可以通过HTTP或HTTPS协议发送),并获取VPC服务对该请求响应结果的过程。VPC服务端在接收到用户请求后,对请求做必要的身份验证和参数验证,在所有验证成功后根据请求的指定参数提交并完成相应操作,并把处理的结果以HTTP响应的形式返回给调用者。

请求结构

请求由以下几个部分组成:

HTTP方法:目前VPC服务的所有接口只支持GET方法的调用。

请求URL:请求的服务地址、要执行的操作名称、操作参数和公共请求参数都包含在请求的URL中。

服务端地址:VPC服务的域名是http://vpc.aliyuncs.com/https://vpc.aliyuncs.com/。为了保证请求的安全性,强烈推荐您使用HTTPS通道。 (HTTPS加入了SSL层对通信进行了加密,可以防止通信被截获而导致敏感信息泄露。)

操作名称:每个接口都需要指定要执行的操作名称,即Action参数。

操作参数:根据要执行的操作不同,需要传入不同的操作参数,详见每个接口的说明。

公共请求参数:包含时间戳、签名信息等每个请求都要包含的参数。

为了使服务端能够正确地验证用户的身份并授权请求执行,请求在提交前要进行签名处理。签名的规则参见签名机制一节。

在服务端对请求处理完成后,会返回响应结果。响应结果分为成功结果和错误消息,格式描述参见返回结果一节。客户端可以解析响应的消息体,得到执行结果。

调用示例

DescribeRegions接口为例:

对应的Action是DescribeRegions,该接口用于查询可用地域列表, 因为该接口没有自定义的参数,所以只需要添加公共请求参数(除了Signature, 该参数需要后面通过签名算法计算出来)。添加了参数之后,请求的URL如下(为了便于阅读,这里展示的是进行URL编码前的URL):

  1. http://vpc.aliyuncs.com/?TimeStamp=2016-02-23T12:46:24Z&Format=XML&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2016-04-28&SignatureVersion=1.0
  1. 按照签名计算规则,先构造出规范化请求字符串(Canonicalized Query String),如下:
    1. AccessKeyId=testid&Action=DescribeRegions&Format=XML&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&SignatureVersion=1.0&TimeStamp=2016-02-23T12%3A46%3A24Z&Version=2016-04-28
  2. 再构造出用于签名的字符串StringToSign值为:

    1. GET&%2F&AccessKeyId%3Dtestid&Action%3DDescribeRegions&Format%3DXML&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3D3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&SignatureVersion%3D1.0&TimeStamp%3D2016-02-23T12%253A46%253A24Z&Version%3D2016-04-28

    以下Java示例代码演示了如何添加公共请求参数、如何用请求参数构造规范化请求字符串,以及如何构造StringToSign字符串。示例假定所有请求参数放在一个Map<String, String>对象里,使用的AccessKey ID是testid

    1. final String HTTP_METHOD = "GET";
    2. Map<String, String> parameters = new HashMap<String, String>();
    3. // 加入请求参数
    4. parameters.put("Action", "DescribeRegions");
    5. parameters.put("Version", "2016-04-28");
    6. parameters.put("AccessKeyId", "testid");
    7. parameters.put("TimeStamp", formatIso8601Date(new Date()));
    8. parameters.put("SignatureMethod", "HMAC-SHA1");
    9. parameters.put("SignatureVersion", "1.0");
    10. parameters.put("SignatureNonce", UUID.randomUUID().toString());
    11. parameters.put("Format", "XML");
    12. // 对参数进行排序
    13. String[] sortedKeys = parameters.keySet().toArray(new String[]{});
    14. Arrays.sort(sortedKeys);
    15. final String SEPARATOR = "&";
    16. // 生成stringToSign字符串
    17. StringBuilder stringToSign = new StringBuilder();
    18. stringToSign.append(HTTP_METHOD).append(SEPARATOR);
    19. stringToSign.append(percentEncode("/")).append(SEPARATOR);
    20. StringBuilder canonicalizedQueryString = new StringBuilder();
    21. for(String key : sortedKeys) {
    22. // 这里注意对key和value进行编码
    23. canonicalizedQueryString.append("&")
    24. .append(percentEncode(key)).append("=")
    25. .append(percentEncode(parameters.get(key)));
    26. }
    27. // 这里注意对canonicalizedQueryString进行编码
    28. stringToSign.append(percentEncode(
    29. canonicalizedQueryString.toString().substring(1)));

    下面的示例代码演示了如何生成符合规范的TimeStamp字符串:

    NoteTimeStamp参数要求符合ISO8601规范,并注意使用UTC时间,否则会遇到错误。

    1. private static final String ISO8601_DATE_FORMAT = "yyyy-MM-dd'T'HH:mm:ss'Z'";
    2. private static String formatIso8601Date(Date date) {
    3. SimpleDateFormat df = new SimpleDateFormat(ISO8601_DATE_FORMAT);
    4. df.setTimeZone(new SimpleTimeZone(0, "GMT"));
    5. return df.format(date);
    6. }

    生成规范化请求字符串(示例中的canonicalizedQueryString变量),以及SringToSign时,都需要进行必要的编码。编码的规则在签名机制一节中有详细描述。下面的示例代码演示了编码的算法:

    1. private static final String ENCODING = "UTF-8";
    2. private static String percentEncode(String value) throws UnsupportedEncodingException {
    3. return value != null ? URLEncoder.encode(value, ENCODING).replace("+", "%20").replace("*", "%2A").replace("%7E", "~") : null;
    4. }
  3. 假设使用的AccessKey Id是testid, AccessKey Secret是testsecret,用于计算HMAC的Key就是testsecret&,最终计算得到的签名值为:

    1. CT9X0VtwR86fNWSnsc6v8YGOjuE=

    计算签名的示例代码(Java):

    1. // 以下是一段计算签名的示例代码
    2. final String ALGORITHM = "HmacSHA1";
    3. final String ENCODING = "UTF-8";
    4. key = "testsecret&";
    5. Mac mac = Mac.getInstance(ALGORITHM);
    6. mac.init(new SecretKeySpec(key.getBytes(ENCODING), ALGORITHM));
    7. byte[] signData = mac.doFinal(stringToSign.getBytes(ENCODING));
    8. String signature = new String(Base64.encodeBase64(signData));
  4. 将签名作为Signature参数加入到URL请求中,最后得到的URL为:
    1. http://vpc.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeRegions&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2016-04-28&AccessKeyId=testid&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureMethod=HMAC-SHA1&TimeStamp=2016-02-23T12%3A46%3A24Z
    然后通过HTTP请求的方式向上面的URL地址发送HTTP请求,并得到VPC服务端的响应结果(示例):
    1. <DescribeRegionsResponse>
    2. <Regions>
    3. <Region>
    4. <LocalName>青岛节点</LocalName>
    5. <RegionId>cn-qingdao</RegionId>
    6. </Region>
    7. <Region>
    8. <LocalName>杭州节点</LocalName>
    9. <RegionId>cn-hangzhou</RegionId>
    10. </Region>
    11. </Regions>
    12. <RequestId>833C6B2C-E309-45D4-A5C3-03A7A7A48ACF</RequestId>
    13. </DescribeRegionsResponse>
    通过解析这个XML结果即可以得到所有可用的地域Id和LocalName的列表。如果在提交请求时,指定Format参数为JSON,那么返回结果的格式为JSON格式。
本文导读目录