泛化调用
阿里云SDK支持一种通用的方式调用OpenAPI,此方式被称为泛化调用。本文将为您详细介绍如何使用泛化调用访问OpenAPI。
特点
轻量:仅需安装阿里云核心SDK,无需额外安装云产品SDK。
简单:只需构造通用的请求参数对象,然后利用通用请求客户端调用通用函数发起请求,调用结果也以通用格式返回。
更多介绍,请参见泛化调用与特化调用。
使用说明
使用泛化调用时,建议先查看OpenAPI元数据,获取OpenAPI的API风格、请求参数、资源路径等信息。
安装核心SDK
在Terminal中执行以下命令安装核心SDK。
composer require alibabacloud/darabonba-openapi
调用OpenAPI
初始化请求客户端
通过创建OpenApiClient
对象初始化请求客户端,并通过该Client发起OpenAPI调用。在初始化客户端时,也支持使用Credentials工具,关于Credentials工具的更多信息,请参见管理访问凭据。
// getenv表示从环境变量中获取访问密钥,确保环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET 已设置。
$config = new Config([
"accessKeyId" => getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
"accessKeySecret" => getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
]);
// 设置 API 调用的服务接入点,这里以 ECS 服务的 Hangzhou 地域为例。
$config->endpoint = "ecs-cn-hangzhou.aliyuncs.com";
// $config->protocol = "HTTPS"; // 配置协议类型为 HTTPS
$client = new OpenApiClient($config);
// 使用默认凭证初始化Credentials Client。
// $credentialClient = new Credential();
// $Config = new Config([
// // 使用 credential 配置凭证
// 'credential' => $credentialClient,
// // 产品服务域名
// 'endpoint' => 'ecs-cn-hangzhou.aliyuncs.com'
// ]);
// $client = new OpenApiClient($Config);
配置OpenAPI信息
通过Params
配置OpenAPI的基本信息,比如OpenAPI的风格、API版本、请求方式等信息。
$params = new Params([
"action" => "DescribeInstanceTypeFamilies", // API名称
"version" => "2014-05-26", // API版本
"protocol" => "HTTPS", // API协议
"method" => "POST", // API请求方法
"authType" => "AK", // 鉴权类型
"pathname" => "/", // 接口 PATH
"reqBodyType" => "json", // 接口请求体内容格式
"bodyType" => "json",// json类型请求体
"style" => "RPC" // 请求风格:RPC或ROA
]);
配置请求参数
通过OpenApiRequest
配置请求参数请求参数支持通过query、body或stream传参,如何选择传参方式可根据元数据中的介绍选择,例如DescribeInstanceTypeFamilies
的请求参数RegionId在元数据中信息为{"name":"RegionId","in":"query",...}}
,其中"in":"query"
表示RegionId通过query传递。
传参方式 | 描述 |
query | 请求参数显示 |
body | 请求参数显示 |
stream | 在需要上传文件的场景,可通过stream传递文件流。 |
// 场景一:设置查询参数(query)
$query = ["RegionId" => "cn-hangzhou"];
$request = new OpenApiRequest([
"query" => OpenApiUtilClient::query($query),
]);
// 场景二:设置body参数,reqBodyType的值为json
// $body = [
// "param1" => "value1"
// ];
// $request = new OpenApiRequest([
// "body" => OpenApiUtilClient::query($body)
// ]);
// 场景三:使用stream参数传递文件流
// $request = new OpenApiRequest([
// "stream" => "<FILE_STREAM>", // 传递文件流
// ]);
// 场景四:设置body参数,reqBodyType的值为formData
// $formData = [
// "param1" => "value1",
// ];
// $request = new OpenApiRequest([
// "body" => $formData,
// ]);
发起请求
通过OpenApiClient
调用callApi发起请求。同时,在请求过程中支持设置运行时参数,例如超时配置、代理配置等,更多信息请查看进阶配置。
// 创建RuntimeOptions实例,可以在这里配置运行时选项,如超时时间等。
$runtime = new RuntimeOptions([]);
// $runtime -> ignoreSSL = true; // true 忽略证书校验;false 设置证书校验
// $runtime -> httpProxy = "http://127.0.0.1:8080"; // 代理配置
// $runtime -> httpsProxy = "https://username:password@proxyServer:port";
// $runtime -> noProxy = "127.0.0.1,localhost";
// 返回值为 Map 类型,可从 Map 中获得三类数据:响应体 body、响应头 headers、HTTP 返回的状态码 statusCode。
$response = $client->callApi($params, $request, $runtime);
var_dump($response);
代码示例
示例:调用RPC风格的API
以调用ECS的DescribeRegions接口为例,展示如何使用泛化调用方式。
<?php
namespace AlibabaCloud\SDK\Sample;
require_once 'vendor/autoload.php';
use AlibabaCloud\Credentials\Credential;
use AlibabaCloud\Tea\Utils\Utils;
use AlibabaCloud\OpenApiUtil\OpenApiUtilClient;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;
use Darabonba\OpenApi\Models\Config;
use Darabonba\OpenApi\Models\OpenApiRequest;
use Darabonba\OpenApi\Models\Params;
use Darabonba\OpenApi\OpenApiClient;
class Sample
{
public static function main()
{
// 从环境变量中获取访问密钥,确保环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET 已设置。
$config = new Config([
"accessKeyId" => getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
"accessKeySecret" => getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
]);
// 设置 API 调用的服务接入点,这里以 ECS 服务的 Hangzhou 地域为例。
$config->endpoint = "ecs-cn-hangzhou.aliyuncs.com";
$client = new OpenApiClient($config);
$params = new Params([
"action" => "DescribeInstanceTypeFamilies", // API名称
"version" => "2014-05-26", // API版本
"protocol" => "HTTPS", // API协议
"method" => "POST", // API请求方法
"authType" => "AK", // 鉴权类型
"style" => "RPC", // 请求风格
"pathname" => "/", // 接口 PATH
"reqBodyType" => "json", // 接口请求体内容格式
"bodyType" => "json",// json类型请求体
]);
// 设置查询参数
$query = ["RegionId" => "cn-hangzhou"];
$request = new OpenApiRequest([
"query" => OpenApiUtilClient::query($query),
]);
// 创建RuntimeOptions实例,可以在这里配置运行时选项,如超时时间等。
$runtime = new RuntimeOptions([]);
// 返回值为 Map 类型,可从 Map 中获得三类数据:响应体 body、响应头 headers、HTTP 返回的状态码 statusCode。
$response = $client->callApi($params, $request, $runtime);
var_dump($response);
}
}
Sample::main();
示例:调用RESTful(ROA)风格的API
以调用容器服务查询集群列表信息为例,展示如何使用泛化调用。
<?php
namespace AlibabaCloud\SDK\Sample;
require_once 'vendor/autoload.php';
use Darabonba\OpenApi\OpenApiClient;
use AlibabaCloud\OpenApiUtil\OpenApiUtilClient;
use Darabonba\OpenApi\Models\Config;
use Darabonba\OpenApi\Models\Params;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;
use Darabonba\OpenApi\Models\OpenApiRequest;
class Sample
{
public static function main()
{
$config = new Config([
"accessKeyId" => getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
"accessKeySecret" => getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
]);
$config->endpoint = "cs.cn-qingdao.aliyuncs.com";
$client = new OpenApiClient($config);
$params = new Params([
// 接口名称
"action" => "DescribeClustersV1",
// 接口版本
"version" => "2015-12-15",
// 接口协议
"protocol" => "HTTPS",
// 接口 HTTP 方法
"method" => "GET",
"authType" => "AK",
"style" => "ROA",
// 接口 PATH
"pathname" => "/api/v1/clusters",
// 接口请求体内容格式
"reqBodyType" => "json",
// 接口响应体内容格式
"bodyType" => "json"
]);
// query params
$queries = [
"name" => "cluster-demo"
];
$request = new OpenApiRequest([
"query" => OpenApiUtilClient::query($queries)
]);
// runtime options
$runtime = new RuntimeOptions([]);
// 返回值为 Map 类型,可从 Map 中获得三类数据:响应体 body、响应头 headers、HTTP 返回的状态码 statusCode。
$response = $client->callApi($params, $request, $runtime);
var_dump($response);
}
}
Sample::main();