使用CommonRequest調用.NET SDK - Alibaba Cloud SDK

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

特點

輕量：只需Core包即可發起調用，無需下載安裝各產品的SDK。
相容性高：當雲產品尚未提供相應的SDK，或當新API發布但SDK未能及時更新時，可以使用泛化調用。這樣，無需等待SDK的更新，即可及時調用最新發行的API介面。

使用說明

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

安裝核心SDK

在Terminal中執行以下命令安裝核心SDK，最新版本請參見aliyun-net-sdk-core。

dotnet add package aliyun-net-sdk-core

調用OpenAPI

初始化請求用戶端

通過建立DefaultAcsClient初始化請求用戶端，樣本中以使用AccessKey初始化用戶端方式為例，更多初始化方式請參見管理訪問憑據。

說明

為了避免憑據泄露，常見的方案是將其寫入到環境變數中，具體操作請參見在Linux、macOS和Windows系統配置環境變數。

using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Profile;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {
        public static void Main(string[] args)
        {
            IClientProfile profile = DefaultProfile.GetProfile(
                // 地區ID
                "<REGION_ID>",
                // 從環境變數擷取RAM使用者的AccessKey ID
                Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // 從環境變數擷取RAM使用者的AccessKey SECRET
                Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
            DefaultAcsClient client = new DefaultAcsClient(profile);
        }
    }
}

配置OpenAPI資訊及請求參數

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

介面請求參數說明

請求參數應該如何傳參需要查看介面對應的OpenAPI中繼資料，例如DescribeInstanceStatus的請求參數RegionId在中繼資料中資訊為{"name":"RegionId","in":"query",...}}，其中"in":"query"表示RegionId通過AddQueryParameters傳遞。

描述	傳參方式
請求參數顯示`"in":"query"`時。	AddQueryParameters(string key,string value) 說明如果請求參數的類型是集合，那麼參數應該按照AddQueryParameters("key.1","value1")、AddQueryParameters("key.2","value2")...格式傳參。
請求參數顯示`"in":"body"`或`"in": "formData"`時。	AddBodyParameters(string key,string value) 說明如果請求參數的類型不是字串類型，則需要將參數值轉換為JSON字串，並賦值給變數value。
上傳檔案時。	SetContent(byte[] content,string charset,FormatType formatType) 說明其中參數formatType固定為FormatType.RAW。

       // 2. 建立API請求，並設定參數
        CommonRequest request = new CommonRequest();
        // 2.1  設定公用請求參數
        request.Domain = "ecs-cn-hangzhou.aliyuncs.com"; // 對應雲產品支援的endpoint
        request.Version = "2014-05-26"; // 對應雲產品的API版本
        request.Action = "DescribeInstanceStatus"; // 介面名稱，RPC必傳，ROA非必傳
        request.Method = MethodType.POST; // 佈建要求方式，MethodType.POST、MethodType.GET、MethodType.PUT、MethodType.DELETE、MethodType.HEAD、MethodType.OPTIONS
        request.Protocol = ProtocolType.HTTPS; // 佈建要求協議，ProtocolType.HTTPS、ProtocolType.HTTP
        request.TimeoutInMilliSeconds = 1000; // 逾時時間
        // request.UriPattern = "/";  // 資源路徑，ROA介面必傳。RPC介面禁止設定該參數。

        // 2.2 設定介面請求參數
        // 情境一：Query參數通過AddQueryParameters(string key,string value)設定
        request.AddQueryParameters("RegionId", "cn-hangzhou");
        List<string> instanceIds = new List<string> { "i-bp124uve8zq7XXXXXXXX", "i-bp1axhql4dqaXXXXXXXX" };
        for (int i = 0; i < instanceIds.Count; i++) {
		request.AddQueryParameters($"InstanceId.{i + 1}" , instanceIds[i]);
	    }
        request.AddQueryParameters("PageNumber", "1");
        request.AddQueryParameters("PageSize", "30");

        // 情境二：body參數通過AddBodyParameters(string key,string value)設定
        // request.AddBodyParameters("key1", "value1");
        // request.AddBodyParameters("key2", "value2");

        // 情境三：檔案上傳SetContent(byte[] content,string charset,FormatType formatType)，其中formatType固定為FormatType.RAW。
        // byte[] content = File.ReadAllBytes(@"<FILE_PATH>");
        // request.SetContent(content, "UTF-8",FormatType.RAW);

發起請求

通過前面步驟建立的client調用GetCommonResponse發起請求。

CommonResponse response = client.GetCommonResponse(request);
System.Console.WriteLine(response.Data);

樣本：調用RPC風格的API

以下代碼展示了如何使用CommonRequest的方式調用ECS的DescribeInstanceStatus介面：

using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Exceptions;
using Aliyun.Acs.Core.Profile;
class Sample
{
    static void Main(string[] args)
    {
        // 構建一個用戶端執行個體，用於發起請求
        IClientProfile profile = DefaultProfile.GetProfile(
            // 地區ID
            "cn-hangzhou",
            // 從環境變數擷取RAM帳號的AccessKey ID
            Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
            // 從環境變數擷取RAM帳號的AccessKey SECRET
            Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        DefaultAcsClient client = new DefaultAcsClient(profile);
        try
        {
            // 構造請求
            CommonRequest request = new CommonRequest();
            request.Domain = "ecs.aliyuncs.com";
            request.Version = "2014-05-26";
            // 因為是 RPC 風格介面，需指定 ApiName(Action)
            request.Action = "DescribeInstanceStatus";
            request.AddQueryParameters("RegionId", "cn-hangzhou");
            List<string> instanceIds = new List<string> { "i-bp124uve8zq7XXXXXXXX", "i-bp1axhql4dqaXXXXXXXX" };
            for (int i = 0; i < instanceIds.Count; i++) {
                    request.AddQueryParameters($"InstanceId.{i + 1}" , instanceIds[i]);
                }
            request.AddQueryParameters("PageNumber", "1");
            request.AddQueryParameters("PageSize", "30");
            // 發起請求，並得到 Response
            CommonResponse response = client.GetCommonResponse(request);
            System.Console.WriteLine(response.Data);
        }
        catch (ServerException ex)
        {
            System.Console.WriteLine(ex.ToString());
        }
        catch (ClientException ex)
        {
            System.Console.WriteLine(ex.ToString());
        }
    }
}

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

以下代碼展示了如何使用CommonRequest的方式調用Container Service的查看所有叢集執行個體介面：

using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Exceptions;
using Aliyun.Acs.Core.Profile;
class Sample
{
    static void Main(string[] args)
    {
        // 構建一個 Client，用於發起請求
        IClientProfile profile = DefaultProfile.GetProfile(
            // 地區ID
            "<REGION-ID>",
            // 從環境變數擷取RAM帳號的AccessKey ID
            Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
            // 從環境變數擷取RAM帳號的AccessKey SECRET
            Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        DefaultAcsClient client = new DefaultAcsClient(profile);
        try
        {
            // 構造請求
            CommonRequest request = new CommonRequest();
            request.Domain = "cs.aliyuncs.com";
            request.Version = "2015-12-15";
            // 因為是Restful風格介面，需指定 UriPattern
            request.UriPattern = "/clusters";
            // 發起請求，並得到 Response
            CommonResponse response = client.GetCommonResponse(request);
            System.Console.WriteLine(response.Data);
        }
        catch (ServerException ex)
        {
            System.Console.WriteLine(ex.ToString());
        }
        catch (ClientException ex)
        {
            System.Console.WriteLine(ex.ToString());
        }
    }
}

常見問題

報錯提示“The input parameter \"AccessKeyId\" that is mandatory for processing this request is not supplied.”。
問題原因：AK未正確配置。
解決方案：
1. 執行以下命令，檢查您的環境變數中是否配置有ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET：
  Linux/macOS
```
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET
```
  Windows
```
echo %ALIBABA_CLOUD_ACCESS_KEY_ID%
echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%
```
  若返回正確的AccessKey，則說明配置成功。如果返回為空白或錯誤，請嘗試重新設定，具體操作請參見在Linux、macOS和Windows系統配置環境變數。
2. 檢查代碼中AK相關內容是否存在錯誤。
  常見錯誤樣本：
```
AccessKeyId = Environment.GetEnvironmentVariable("yourAccessKeyID"),
AccessKeySecret = Environment.GetEnvironmentVariable("yourAccessKeySecret"),
```
  正確樣本
```
Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"), 
Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
```
報錯提示“Unhandled exception. Aliyun.Acs.Core.Exceptions.ClientException: SDK.WebException : HttpWebRequest WebException occured, the request url is XXX.cn-hangzhou.aliyuncs.com System.Net.WebException: An eile sending the request.”
問題原因：RPC介面公用請求參數設定了UriPattern參數。
解決方案：在公用請求參數中去掉UriPattern參數。

特點