PHP V2.0 SDK泛化調用 - Alibaba Cloud SDK

阿里雲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	請求參數顯示`"in":"query"`時，通過query傳遞參數。
body	請求參數顯示`"in":"body"`或`"in": "formData"`時，通過body傳遞參數。在使用請求體（body）傳遞參數時，需要根據請求體的類型設定`reqBodyType`的值。
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的DescribeInstanceTypeFamilies介面為例，展示如何使用泛化調用方式。

<?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

以調用Container Service查詢叢集列表資訊為例，展示如何使用泛化調用。

<?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();