ECS PHP V2.0 SDK调用示例

本文以调用查询一台或多台ECS实例的详细信息(DescribeInstances)接口为例,为您介绍PHP V2.0 SDK的安装和使用。

前提条件

  1. 由于阿里云账号(主账号)拥有资源的所有权限,其AccessKey一旦泄露风险巨大,所以建议您使用满足最小化权限需求的RAM用户的AccessKey。具体操作方式请参见创建AccessKey

  2. 给RAM用户授予操作云服务器ECS相关资源的权限。本文提供的示例代码为查询示例,所以选择AliyunECSReadonlyAccess系统权限策略,您在使用的时候可以根据业务需求进行自定义授权。

    1. 使用自定义权限策略。

      关于如何创建自定义权限策略,请参见创建自定义权限策略授权信息

      云服务器ECS依据最佳实践提供了一些自定义权限策略示例,您可以参考这些示例以快速创建符合自身业务需求的自定义权限策略,具体详情请参见云服务器ECS自定义权限策略参考

    2. 使用系统权限策略。

      云服务器ECS支持的所有系统权限策略及其对应的权限描述,请参见云服务器 ECS系统权限策略参考

  3. 在环境变量中配置AccessKey,具体操作步骤请参见在Linux、macOS和Windows系统配置环境变量

安装SDK

PHP V2.0 SDK安装方式请参见SDK 中心。您可以直接复制下方提供的安装命令在Terminal中执行,以完成ECS SDK的安装:

composer require alibabacloud/ecs-20140526 4.3.0

使用SDK

1. 初始化客户端

阿里云SDK支持多种访问凭据用于初始化客户端,例如AccessKey和STS Token等,更多方式请参见管理访问凭据。本示例以通过AccessKey初始化客户端为例。

<?php

require_once 'vendor/autoload.php';
use AlibabaCloud\SDK\Ecs\V20140526\Ecs;
use Darabonba\OpenApi\Models\Config;

class Sample
{
    public static function createClient()
    {
        $config = new Config([
            // 必填,请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID
            "accessKeyId" => getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
            // 必填,请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_SECRET
            "accessKeySecret" => getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
            "endpoint" => "ecs.cn-hangzhou.aliyuncs.com",
        ]);
        return new Ecs($config);
    }
}

2. 构建接口的请求对象

在构建请求对象之前,请查看该接口的API文档获取参数信息。

说明

请求对象命名规则:{API名称}Request,例如DescribeInstances该接口的请求对象为DescribeInstancesRequest。

// 构造请求对象
$describeInstancesRequest = new DescribeInstancesRequest([
     "regionId" => "cn-beijing"
]);

3. 发起调用

通过客户端调用OpenAPI时,支持设置运行时参数,例如超时配置、代理配置等,更多信息请查看进阶配置

说明

接口返回对象命名规则:{API名称}Response,例如DescribeInstances该接口的返回对象为DescribeInstancesResponse。

// 创建运行时配置对象
$runtime = new RuntimeOptions();
// 发起请求  
$describeInstancesResponse = $client->describeInstancesWithOptions($describeInstancesRequest, $runtime);

4. 异常处理

PHP SDK将异常进行了细致的分类,主要划分为以下几个:

  • TeaUnableRetryError:该异常主要是因为网络问题造成,一般是网络问题造成达到最大重试次数后抛出,可以通过getLastException来查询错误发生时的请求信息。

  • TeaError:在SDK的请求中主要以业务报错为主的异常。

建议采取合理的措施来处理异常,比如合理地传播异常、记录日志、尝试恢复等,以确保系统的健壮性和稳定性。

5. 完整示例

<?php

require_once 'vendor/autoload.php';
use AlibabaCloud\SDK\Ecs\V20140526\Ecs;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;
use Darabonba\OpenApi\Models\Config;
use AlibabaCloud\SDK\Ecs\V20140526\Models\DescribeInstancesRequest;
use AlibabaCloud\Tea\Exception\TeaError;
use AlibabaCloud\Tea\Exception\TeaUnableRetryError;

class Sample
{

    public static function main()
    {
        try {
            $config = new Config([
                "accessKeyId" => getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                "accessKeySecret" => getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
                "endpoint" => "ecs.cn-beijing.aliyuncs.com", // <endpoint>
            ]);
            $client = new Ecs($config);

            // 构造请求对象
            $describeInstancesRequest = new DescribeInstancesRequest([
                "regionId" => "cn-beijing"
            ]);
            // 创建运行时配置对象
            $runtime = new RuntimeOptions();
            // 发起请求  
            $describeInstancesResponse = $client->describeInstancesWithOptions($describeInstancesRequest, $runtime);
            var_dump($describeInstancesResponse);
        } catch (\Exception $error) {
            if ($error instanceof TeaError) {
                // 此处仅做打印展示,请谨慎对待异常处理,在工程项目中切勿直接忽略异常。
                print_r("message:" . $error->getMessage() . "\n");
                print_r("code:" . $error->getCode() . "\n");
                print_r($error->data);
            } elseif ($error instanceof TeaUnableRetryError) {
                // 此处仅做打印展示,请谨慎对待异常处理,在工程项目中切勿直接忽略异常。
                print_r($error->getLastException());
            } else {
                // 此处仅做打印展示,请谨慎对待异常处理,在工程项目中切勿直接忽略异常。
                print_r("message:" . $error->getMessage());
            }
        }
    }
}
Sample::main();

场景化示例

更多内容

除了使用上述调用方式外,您还可以使用泛化调用方式调用ECS的OpenAPI,详细介绍请参见泛化调用

若您当前使用的是V1.0 SDK,并希望进一步了解V1.0 SDK的相关内容,请参见V1.0 PHP SDK