全部产品
存储与CDN 数据库 域名与网站(万网) 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 钉钉智能硬件
阿里云SDK开发指南

使用CommonRequest

更新时间:2018-02-02 15:18:56

Common调用方式

当您需要访问的 API 没有产品 SDK 提供时。可以采用泛用型的 AP I调用方式,使用 CommonRequest,实现任意 OpenAPI 接口的调用,CommonReques有如下特点:

  • 轻量:只需 Core 包即可发起调用,无需下载安装各产品线 SDK。
  • 简便:无需更新 SDK 即可调用最新发布的 API。
  • 快速迭代。

如何使用

使用 CommonRequest 时,请配合相应的 API 文档使用,以查询 API 的相关信息,您可以在文档中心查询到所有产品的 API 文档。

发起一次 Common 请求,需要您查询到以下几个参数:

  • 域名(domain):即该产品的通用访问域名,如 ecs.aliyuncs.com,通常可以在”调用方式”页面获取。

  • API版本(version):即该产品 API 的版本号,以 YYYY-MM-DD 的形式表现,如 2017-12-07,一般可以在”公共参数”页面获取。

    注意: 在”公共参数”页面中,version 字段一般以 Version 参数体现,部分页面以 x-acs-version 参数体现。

  • 当调用的 OpenAPI 为 Rpc 风格接口时(大部分阿里云产品 OpenAPI 为 Rpc 风格),例如:ECS、RDS,需要赋值以下字段:

    • Action 字段,例如 ECS-RunInstances 的 Action 为 RunInstances,在这种情况下,您可以通过 request.setQueryParameter("Action", "RunInstances") 来指定
  • 当调用的 OpenAPI 风格为 Restful 风格接口时,例如:CS(容器服务), 需要赋值以下字段:

    • ResourcePath 字段,例如容器服务-查看所有集群实例会包含一段类似 GET /clusters HTTP/1.1 的 RequestLine,在这种情况下,您可以通过 request.setResourcePath("/clusters") 来指定

Tips: 如何区分 Rpc 风格和 Restful 风格

  • 简单来说,API 参数中包含 Action 字段的是RPC风格,
  • 需要指定请求资源路径的是 Restful 风格。一般情况下,每个产品内,所有 API 的调用风格是统一的
  • 每个 API 仅支持特定的一种风格调用,传入错误的标识,可能会调用到其他 API,或收到“ApiNotFound”的错误信息

OpenAPI Explorer

部分产品,您也可以通过 https://api.aliyun.com 来获取 API 的参数信息。

示例代码

调用 RPC 风格接口

以下我们以云服务器 ECS 产品的 DescribeInstanceStatus API 为例,展示如何通过 CommonAPI 的方式调用 RPC 风格接口,该接口信息也可以在 OpenAPI Explorer - DescribeInstanceStatus中找到

注意: 您需要替换示例中的 your-region-id、your-access-key-id 和 your-access-key-secret 的值。

  1. #include <iostream>
  2. #include <alibabacloud/core/AlibabaCloud.h>
  3. #include <alibabacloud/core/CommonClient.h>
  4. using namespace AlibabaCloud;
  5. int main(int argc, char** argv)
  6. {
  7. // 初始化 SDK
  8. AlibabaCloud::InitializeSdk();
  9. // 配置 ecs 实例
  10. ClientConfiguration configuration("<your-region-id>");
  11. CommonClient client("<your-access-key-id>", "<your-access-key-secret>", configuration);
  12. // 创建API请求并设置参数
  13. CommonRequest request(CommonRequest::RpcPattern);
  14. request.setDomain("ecs.aliyuncs.com");
  15. request.setVersion("2014-05-26");
  16. // 因为是 RPC 风格接口,需指定 ApiName(Action)
  17. request.setQueryParameter("Action", "DescribeInstanceStatus");
  18. request.setQueryParameter("PageNumber", "1");
  19. request.setQueryParameter("PageSize", "30");
  20. auto outcome = client.commonResponse(request);
  21. if (!outcome.isSuccess())
  22. {
  23. // 异常处理
  24. std::cout << outcome.error().errorCode() << std::endl;
  25. AlibabaCloud::ShutdownSdk();
  26. return -1;
  27. }
  28. std::cout << "result: " << outcome.result().payload() << std::endl;
  29. // 关闭 SDK
  30. AlibabaCloud::ShutdownSdk();
  31. return 0;
  32. }

调用Restful风格接口

以下我们以容器服务的查看所有集群实例 API 为例,展示如何通过 CommonAPI 的方式调用 Restful 风格接口。

注意: 您需要替换示例中的 your-region-id、your-access-key-id 和 your-access-key-secret 的值。

  1. #include <iostream>
  2. #include <alibabacloud/core/AlibabaCloud.h>
  3. #include <alibabacloud/core/CommonClient.h>
  4. using namespace AlibabaCloud;
  5. int main(int argc, char** argv)
  6. {
  7. // 初始化 SDK
  8. AlibabaCloud::InitializeSdk();
  9. // 配置 ecs 实例
  10. ClientConfiguration configuration("<your-region-id>");
  11. CommonClient client("<your-access-key-id>", "<your-access-key-secret>", configuration);
  12. // 创建API请求并设置参数
  13. CommonRequest request(CommonRequest::RoaPattern);
  14. request.setDomain("cs.aliyuncs.com");
  15. request.setVersion("2015-12-15");
  16. // 因为是 Restful 风格接口,需指定 ResourcePath
  17. request.setResourcePath("/clusters");
  18. auto outcome = client.commonResponse(request);
  19. if (!outcome.isSuccess())
  20. {
  21. // 异常处理
  22. std::cout << outcome.error().errorCode() << std::endl;
  23. AlibabaCloud::ShutdownSdk();
  24. return -1;
  25. }
  26. std::cout << "result: " << outcome.result().payload() << std::endl;
  27. // 关闭 SDK
  28. AlibabaCloud::ShutdownSdk();
  29. return 0;
  30. }
本文导读目录