Alibaba Cloud SDK：泛化調用

特點

1. 輕量級：僅需安裝Core包即可調用所有OpenAPI，無需依賴各產品的獨立SDK。

2. 快速迭代相容性：當雲產品尚未提供相應的SDK，或當新API發布但SDK未能及時更新時，可以使用泛化調用。這樣，無需等待SDK的更新，即可及時調用最新發行的API介面。

更多介紹，請參見泛化調用與特化調用。

使用說明

在使用泛化調用之前，必須手動擷取並配置OpenAPI的版本號碼、請求路徑、參數類型等中繼資料資訊。可以通過查看OpenAPI中繼資料來擷取有關OpenAPI的API風格、請求參數、資源路徑等相關資訊。

安裝核心SDK

在Terminal中執行以下命令安裝核心SDK。

composer require alibabacloud/client

調用OpenAPI

初始化請求用戶端

通過在AlibabaCloud包中建立client以初始化請求用戶端，並通過該Client發起OpenAPI調用。此處僅列舉使用AccessKey（簡稱：AK）初始化用戶端的方式，更多初始化方式請參見管理訪問憑據。

use AlibabaCloud\Client\AlibabaCloud;   

   // getenv代表從環境變數擷取AK，初始化用戶端
    AlibabaCloud::accessKeyClient(
         getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
         getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET')
    )
    ->regionId('cn-hangzhou') // 指定地區
    ->asDefaultClient(); // 設為預設用戶端  
  

配置OpenAPI資訊及請求參數

通過AlibabaCloud包中的client來配置OpenAPI所需的公用請求參數及介面請求參數。關於更多公用請求參數的介紹及使用請參見進階配置。

        // query 查詢參數，參數類型為集合時
        $instanceIDs = ["i-bp1axhql4dqXXXXXXXX", "i-bp124uve8zqXXXXXXXX"];
        // 普通參數
        $queryParams = [
            'RegionId' => 'cn-hangzhou',
            'PageNumber' => 1,
            'PageSize' => 30,
        ]; 
        // 處理集合參數（轉換為InstanceId.1, InstanceId.2格式）
        foreach ($instanceIDs as $index => $id) {
            $queryKey = 'InstanceId.' . ($index + 1);
            $queryParams[$queryKey] = $id;
        }
 // 配置OpenAPI基本資料和請求參數
 $result = AlibabaCloud::rpc() // 介面風格：支援RPC、ROA。
                // 1.配置OpenAPI基本資料
                ->host('ecs.cn-hangzhou.aliyuncs.com') 
                ->product('Ecs') // 產品名稱
                ->version('2014-05-26') // 注意版本號碼需要與API文檔一致
                ->action('DescribeInstanceStatus') // API名稱，當調用RPC風格API時，必須配置action()指定介面名稱
                ->method('POST') // 要求方法：GET、POST
                ->setProtocolType('HTTPS') // 請求協議：HTTPS或HTTP，建議使用HTTPS。
                // ->pathPattern()  // 資源路徑，ROA介面必傳。RPC介面禁止設定該參數。
                // 2.配置請求參數
                ->options([
                    // 情境一：query參數通query設定
                    'query' => $queryParams
                    
                    // 情境二：body參數通過form_params設定
                    // 'form_params' => [ 
                    //     'key1' => 'value1',
                    //     'key2' => 'value2',
                    //     'key3' => 'value3',
                    // ],
                ])
  

發起請求

通過client調用request()發起請求。

 // 調用RPC風格API
 $result = AlibabaCloud::rpc()
           ->request()
 // 調用ROA風格API 
 // $result = AlibabaCloud::roa() 
 //         ->request()        
 // 傳回值是 bytes 類型，包含RequestId以及OpenAPI的返回參數          
 print_r($result->toArray());       

程式碼範例

樣本：調用RPC風格的API

以調用ECS的DescribeRegions介面為例，展示如何使用泛化調用方式。

<?php

namespace AlibabaCloud\SDK\Sample;
require_once 'vendor/autoload.php';
use AlibabaCloud\Tea\Utils\Utils;
use AlibabaCloud\Client\AlibabaCloud;
use AlibabaCloud\Client\Exception\ClientException;
use AlibabaCloud\Client\Exception\ServerException;

class Sample
{   
    public static function main()
    {

    // getenv代表從環境變數擷取AK，初始化用戶端
    AlibabaCloud::accessKeyClient(
         getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
         getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET')
    )
    ->regionId('cn-hangzhou') // 指定地區
    ->asDefaultClient(); // 設為預設用戶端

        // query 查詢參數，參數類型為集合時
        $instanceIDs = ["i-bp1axhql4dqXXXXXXXX", "i-bp124uve8zqXXXXXXXX"];
        // 普通參數
        $queryParams = [
            'RegionId' => 'cn-hangzhou',
            'PageNumber' => 1,
            'PageSize' => 30,
        ]; 
        // 處理集合參數（轉換為InstanceId.1, InstanceId.2）
        foreach ($instanceIDs as $index => $id) {
            $queryKey = 'InstanceId.' . ($index + 1);
            $queryParams[$queryKey] = $id;
        }
        try {
            $result = AlibabaCloud::rpc()
                ->method('POST') // 要求方法
                ->verify(false) // 關閉認證校正
                ->debug(true)  // 開啟日誌
                ->setProtocolType('HTTPS') // 設定協議類型
                ->host('ecs.cn-hangzhou.aliyuncs.com') // 服務地址
                ->version('2014-05-26') // 注意版本號碼需要與API文檔一致
                ->action('DescribeInstanceStatus') // 介面名稱
                // 配置請求參數
                ->options([
                    'query' => $queryParams
                ])
                // 發起請求
                ->request();
            print_r($result->toArray());
        } catch (ClientException | ServerException $e) {
            echo $e->getErrorMessage();
        } catch (ServerException $exception) {
            print_r($exception->getErrorMessage());
        }
}
}

Sample::main();

以下代碼展示了如何使用泛化調用的方式調用Container Service的 DescribeClustersV1 介面：

<?php
namespace AlibabaCloud\SDK\Sample;
require_once 'vendor/autoload.php';
use AlibabaCloud\Client\AlibabaCloud;
use AlibabaCloud\Client\Exception\ClientException;
use AlibabaCloud\Client\Exception\ServerException;

class Sample
{
  public static function main()
    {
    try {
        $result = AlibabaCloud::roa()
                          ->regionId('cn-hangzhou') // 指定請求的地區，不指定則使用用戶端地區、預設地區。
                          ->product('CS') // 指定產品。
                          ->version('2015-12-15') // 指定產品版本。
                          ->serviceCode('cs') // 設定 ServiceCode 以備定址，非必須。
                          ->endpointType('openAPI') // 設定類型，非必須。
                          ->method('GET') // 指定請求方式。
                          ->host('cs.aliyuncs.com') // 指定網域名稱則不會定址，如認證方式為 Bearer Token 的服務則需要指定。
                          ->pathPattern('/api/v1/clusters') // API資源路徑，當調用ROA風格API時，必須配置pathPattern()指定完整資源路徑。從OpenAPI中繼資料中data.path擷取資源路徑。
                          ->request(); // 發起請求並返回結果對象，請求需要放在設定的最後面。
    print_r($result->toArray());
    } catch (ClientException $exception) {
    print_r($exception->getErrorMessage());
    } catch (ServerException $exception) {
    print_r($exception->getErrorMessage());
}
    }
}
Sample::main();