本文以調用查詢一臺或多臺ECS實例的詳細信息(DescribeInstances)接口為例,為您介紹.NET V2.0 SDK的安裝和使用。
前提條件
由于阿里云賬號(主賬號)擁有資源的所有權限,其AccessKey一旦泄露風險巨大,所以建議您使用滿足最小化權限需求的RAM用戶的AccessKey。具體操作方式請參見創建AccessKey。
給RAM用戶授予操作云服務器ECS相關資源的權限。本文提供的示例代碼為查詢示例,所以選擇AliyunECSReadonlyAccess系統權限策略,您在使用的時候可以根據業務需求進行自定義授權。
使用自定義權限策略。
關于如何創建自定義權限策略,請參見創建自定義權限策略和授權信息。
云服務器ECS依據最佳實踐提供了一些自定義權限策略示例,您可以參考這些示例以快速創建符合自身業務需求的自定義權限策略,具體詳情請參見云服務器ECS自定義權限策略參考。
使用系統權限策略。
云服務器ECS支持的所有系統權限策略及其對應的權限描述,請參見云服務器 ECS系統權限策略參考。
在環境變量中配置AccessKey,具體操作步驟請參見在Linux、macOS和Windows系統配置環境變量。
安裝SDK
.NET V2.0 SDK安裝方式請參見SDK 中心,您可以直接從下方提供的安裝方式中選擇適合您的方法,以完成ECS SDK的安裝:
.NET CLI
dotnet add package AlibabaCloud.SDK.Ecs20140526 --version 4.3.1
Package Manager
Install-Package AlibabaCloud.SDK.Ecs20140526 -Version 4.3.1
PackageReference
<PackageReference Include="AlibabaCloud.SDK.Ecs20140526" Version="4.3.1" />
Paket CLI
paket add AlibabaCloud.SDK.Ecs20140526 --version 4.3.1
F# Interactive
#r "nuget: AlibabaCloud.SDK.Ecs20140526, 4.3.1"
使用SDK
1. 初始化客戶端
阿里云SDK支持多種訪問憑據用于初始化客戶端,例如AccessKey和STS Token等,更多方式請參見管理訪問憑證。本示例以通過AccessKey初始化客戶端為例。
namespace ecs
{
public class Sample
{
static void Main(string[] args)
{
var ecsConfig = new AlibabaCloud.OpenApiClient.Models.Config
{
// 從環境變量中獲取AccessKey ID值。
AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
// 從環境變量中獲取AccessKey Secret值。
AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
Endpoint = "ecs.cn-hangzhou.aliyuncs.com"
};
var escClient = new AlibabaCloud.SDK.Ecs20140526.Client(ecsConfig);
}
}
}
2. 構建接口的請求對象
在構建請求對象之前,請查看該接口的API文檔獲取參數信息。
請求對象命名規則:{API名稱}Request,例如DescribeInstances該接口的請求對象為DescribeInstancesRequest。
// 構造請求對象
var describeInstancesRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeInstancesRequest
{
RegionId = "cn-hangzhou"
};
3. 發起調用
通過客戶端調用OpenAPI時,支持設置運行時參數,例如超時配置、代理配置等,更多信息請查看進階配置。
接口返回對象命名規則:{API名稱}Response,例如DescribeInstances該接口的返回對象為DescribeInstancesResponse。
// 創建運行時配置對象
var runtimeOptions = new RuntimeOptions();
// 發起請求
var describeInstancesResponse = escClient.DescribeInstancesWithOptions(describeInstancesRequest, runtimeOptions);
4. 異常處理
.NET SDK將異常進行了細致的分類,主要劃分為以下幾個Exception:
TeaUnretryableException:該異常主要是因為網絡問題造成,一般是網絡問題造成達到最大重試次數后拋出,可以通過
exception.getLastRequest
來查詢錯誤發生時的請求信息。TeaException: 在SDK的請求中主要以業務報錯為主的異常。
建議采取合理的措施來處理異常,比如合理地傳播異常、記錄日志、嘗試恢復等,以確保系統的健壯性和穩定性。
5. 完整示例
using AlibabaCloud.TeaUtil.Models;
using Tea;
namespace ecs
{
public class Sample
{
static void Main(string[] args)
{
var ecsConfig = new AlibabaCloud.OpenApiClient.Models.Config
{
// 從環境變量中獲取AccessKey ID值。
AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
// 從環境變量中獲取AccessKey Secret值。
AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
Endpoint = "ecs.cn-hangzhou.aliyuncs.com"
};
var escClient = new AlibabaCloud.SDK.Ecs20140526.Client(ecsConfig);
// 構造請求對象
var describeInstancesRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeInstancesRequest
{
RegionId = "cn-hangzhou"
};
// 創建運行時配置對象
var runtimeOptions = new RuntimeOptions();
try
{
// 發起請求
var describeInstancesResponse =
escClient.DescribeInstancesWithOptions(describeInstancesRequest, runtimeOptions);
Console.WriteLine(describeInstancesResponse.ToMap());
}
catch (TeaUnretryableException error)
{
// 此處僅做打印展示,請謹慎對待異常處理,在工程項目中切勿直接忽略異常。
Console.WriteLine(error);
}
catch (TeaException error)
{
// 此處僅做打印展示,請謹慎對待異常處理,在工程項目中切勿直接忽略異常。
// 錯誤 message
Console.WriteLine(error.Message);
}
catch (Exception error)
{
// 此處僅做打印展示,請謹慎對待異常處理,在工程項目中切勿直接忽略異常。
Console.WriteLine(error);
}
}
}
}
場景化示例
更多內容
除了使用上述調用方式外,您還可以使用泛化調用方式調用ECS的OpenAPI,詳細介紹請參見泛化調用。
若您當前使用的是V1.0 SDK,并希望進一步了解V1.0 SDK的相關內容,請參見V1.0 .NET SDK。