泛化調用（.NET） - Alibaba Cloud SDK

阿里雲SDK支援一種通用的方式調用OpenAPI，此方式被稱為泛化調用。本文將為您詳細介紹如何使用泛化調用訪問OpenAPI。

特點

輕量：僅需安裝阿里雲核心SDK，無需額外安裝雲產品SDK。

簡單：只需構造通用的請求參數對象，然後利用通用請求用戶端調用通用函數發起請求，調用結果也以通用格式返回。

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

使用說明

使用泛化調用時，建議先查看OpenAPI中繼資料，擷取OpenAPI的API風格、請求參數、資源路徑等資訊。

安裝SDK

在Terminal中執行以下命令安裝核心SDK，最新版本請參見AlibabaCloud.OpenApiClient。

dotnet add package AlibabaCloud.OpenApiClient --version 0.1.13

調用OpenAPI

初始化請求用戶端

通過建立AlibabaCloud.OpenApiClient.Client對象初始化請求用戶端，並通過該Client發起OpenAPI調用。在初始化用戶端時，也支援使用Credentials工具，關於Credentials工具的更多資訊，請參見管理訪問憑證。

        public static AlibabaCloud.OpenApiClient.Client CreateClient()
        {
            AlibabaCloud.OpenApiClient.Models.Config config =
                new AlibabaCloud.OpenApiClient.Models.Config
                {
                    // 必填，請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_ID。
                    AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                    // 必填，請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
                    AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
                };
            config.Endpoint = "ecs-cn-hangzhou.aliyuncs.com";
            return new AlibabaCloud.OpenApiClient.Client(config);
        }
        
        // 使用Credentials工具
        // public static AlibabaCloud.OpenApiClient.Client CreateClient()
        // {
        //     // 使用AK初始化Credentials Client。
        //     Aliyun.Credentials.Models.Config credentialsConfig =
        //         new Aliyun.Credentials.Models.Config()
        //         {
        //             // 憑證類型。
        //             Type = "access_key",
        //             // 從環境變數中擷取AccessKey ID值。
        //             AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
        //             // 從環境變數中擷取AccessKey Secret值。
        //             AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
        //         };
        //     Aliyun.Credentials.Client credentialClient = new Aliyun.Credentials.Client(credentialsConfig);
        //     AlibabaCloud.OpenApiClient.Models.Config config =
        //         new AlibabaCloud.OpenApiClient.Models.Config
        //         {
        //             Credential = credentialClient,
        //             Endpoint = "ecs-cn-hangzhou.aliyuncs.com",
        //         };

        //     return new AlibabaCloud.OpenApiClient.Client(config);
        // }

配置OpenAPI資訊

通過AlibabaCloud.OpenApiClient.Models.Params配置OpenAPI的基本資料，比如OpenAPI的風格、API版本、請求方式等資訊。以調用DescribeInstanceTypeFamilies介面為例：

        AlibabaCloud.OpenApiClient.Models.Params params_ =
            new AlibabaCloud.OpenApiClient.Models.Params
            {
                Action = "DescribeInstanceTypeFamilies", // API名稱。
                Version = "2014-05-26", // API版本號碼。
                Protocol = "HTTPS", // 請求協議：HTTPS或HTTP，建議使用HTTPS。
                Method = "POST", // 要求方法。
                AuthType = "AK", // 認證類型，預設即可。當OpenAPI支援匿名請求時，您可以傳入 Anonymous 發起匿名請求。
                Style = "RPC", // PI風格：RPC或ROA。
                Pathname = "/", // API資源路徑，RPC介面預設"/"，ROA介面從OpenAPI中繼資料中data.path擷取資源路徑。
                ReqBodyType = "json", // 請求body的類型，支援json、formData。
                BodyType = "json", // 返回資料格式，支援json。
            };

配置請求參數

通過AlibabaCloud.OpenApiClient.Models.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）
        Dictionary<string, object> queries = new Dictionary<string, object>() { };
        queries["RegionId"] = "cn-hangzhou";
        AlibabaCloud.OpenApiClient.Models.OpenApiRequest request =
            new AlibabaCloud.OpenApiClient.Models.OpenApiRequest
            {
                Query = AlibabaCloud.OpenApiUtil.Client.Query(queries),
            };

//        // 情境二：設定Body參數，reqBodyType的值為json
//        Dictionary<string, object> body = new Dictionary<string, object>()
//        {
//            { "param1", "value1" },
//            { "param2", "value2" },
//        };
//        AlibabaCloud.OpenApiClient.Models.OpenApiRequest request =
//            new AlibabaCloud.OpenApiClient.Models.OpenApiRequest
//            {
//                Body = AlibabaCloud.OpenApiUtil.Client.Query(body),
//            };

//        // 情境三：設定Body參數，reqBodyType的值為formData
//        Dictionary<string, object> formData = new Dictionary<string, object>()
//        {
//            { "param1", "value1" },
//            { "param2", "value2" },
//        };
//        AlibabaCloud.OpenApiClient.Models.OpenApiRequest request =
//            new AlibabaCloud.OpenApiClient.Models.OpenApiRequest { Body = formData };

//        // 情境四：使用Stream參數傳遞檔案流
//        AlibabaCloud.OpenApiClient.Models.OpenApiRequest request =
//            new AlibabaCloud.OpenApiClient.Models.OpenApiRequest
//            {
//                Stream = "<FILE_STREAM>",
//            };

發起請求

通過AlibabaCloud.OpenApiClient.Client調用CallApi發起請求。同時，在請求過程中支援設定運行時參數，例如逾時配置、代理配置等，更多資訊請查看進階配置。

AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
var response = client.CallApi(params_, request, runtime);
// 傳回值實際為 Map 類型，可從 Map 中獲得三類資料：響應體 body、回應標頭 headers、HTTP返回的狀態代碼 statusCode。
Console.WriteLine(response["statusCode"]);

範例程式碼

樣本：調用RPC風格的API

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

namespace AlibabaCloud.SDK.Sample
{
    public class Sample 
    {

        public static AlibabaCloud.OpenApiClient.Client CreateClient()
        {
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
            {
                // 必填，請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_ID。
                AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // 必填，請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
                AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
            };
            config.Endpoint = "ecs-cn-hangzhou.aliyuncs.com";
            return new AlibabaCloud.OpenApiClient.Client(config);
        }

        public static AlibabaCloud.OpenApiClient.Models.Params CreateApiInfo()
        {
            AlibabaCloud.OpenApiClient.Models.Params params_ = new AlibabaCloud.OpenApiClient.Models.Params
            {
                // 介面名稱
                Action = "DescribeInstanceTypeFamilies",
                // 介面版本
                Version = "2014-05-26",
                // 介面協議
                Protocol = "HTTPS",
                // 介面 HTTP 方法
                Method = "POST",
                AuthType = "AK",
                Style = "RPC",
                // 介面 PATH
                Pathname = "/",
                // 介面請求體內容格式
                ReqBodyType = "json",
                // 介面響應體內容格式
                BodyType = "json",
            };
            return params_;
        }

        public static void Main(string[] args)
        {
            AlibabaCloud.OpenApiClient.Client client = CreateClient();
            AlibabaCloud.OpenApiClient.Models.Params params_ = CreateApiInfo();
            // query params
            Dictionary<string, object> queries = new Dictionary<string, object>(){};
            queries["RegionId"] = "cn-hangzhou";
            // runtime options
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            AlibabaCloud.OpenApiClient.Models.OpenApiRequest request = new AlibabaCloud.OpenApiClient.Models.OpenApiRequest
            {
                Query = AlibabaCloud.OpenApiUtil.Client.Query(queries),
            };
            // 複製代碼運行請自行列印 API 的傳回值
            // 傳回值實際為 Map 類型，可從 Map 中獲得三類資料：響應體 body、回應標頭 headers、HTTP 返回的狀態代碼 statusCode。
            var response = client.CallApi(params_, request, runtime);
            Console.WriteLine(response["statusCode"]);
        }
    }
}

樣本：調用RESTful（ROA）風格的API

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

namespace AlibabaCloud.SDK.Sample
{
    public class Sample 
    {

        public static AlibabaCloud.OpenApiClient.Client CreateClient()
        {
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
            {
                // 必填，請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_ID。
                AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // 必填，請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
                AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
            };
            config.Endpoint = "cs.cn-hangzhou.aliyuncs.com";
            return new AlibabaCloud.OpenApiClient.Client(config);
        }

        public static AlibabaCloud.OpenApiClient.Models.Params CreateApiInfo()
        {
            AlibabaCloud.OpenApiClient.Models.Params params_ = new AlibabaCloud.OpenApiClient.Models.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",
            };
            return params_;
        }

        public static void Main(string[] args)
        {
            AlibabaCloud.OpenApiClient.Client client = CreateClient();
            AlibabaCloud.OpenApiClient.Models.Params params_ = CreateApiInfo();
            // runtime options
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            AlibabaCloud.OpenApiClient.Models.OpenApiRequest request = new AlibabaCloud.OpenApiClient.Models.OpenApiRequest();
            // 複製代碼運行請自行列印 API 的傳回值
            // 傳回值實際為 Map 類型，可從 Map 中獲得三類資料：響應體 body、回應標頭 headers、HTTP 返回的狀態代碼 statusCode。
            var response = client.CallApi(params_, request, runtime);
            Console.WriteLine(response["statusCode"]);
        }
    }
}