.NET SDK

プロダクト紹介

.NET SDKとは

Alibaba Cloud SDK (Software Development Kit) へ ようこそ。Alibaba Cloud .NET SDK を使用すると、 ECS (Elastic Compute Service) 、 RDS (Relational Database Service) 、 CloudMonitor などの Alibaba Cloud サービスにアクセスできます。リクエストの署名や作成などの API 関連のタスクを処理することなく、 Alibaba Cloud サービスにアクセスすることができます。ここでは、NET SDK. のインストール方法と使用方法を 紹介します。

前提条件

  • Alibaba Cloud.NET SDKを使用するために、Alibaba Cloudのアカウントと AccessKey を所有している必要があります。 AccessKey コンソール で AccessKey を作成して表示するか、チケットを起票してサポートセンターへお問い合わせください。
  • Alibaba Cloud.NET SDKを使用してプロダクトの API を呼び出すには、必要に応じて Alibaba Cloud コンソールでまずプロダクトをアクティブ化する必要があります。
  • Alibaba Cloud .NET SDK は NET Framework 4.0 以降に 対応してしています。

Alibaba Cloud .NET SDK の インストール

プロダクトの SDK を呼び出すには、 SDK コアライブラリとプロダクトの SDKを インストールする必要があります。 たとえば、 ECS SDK を呼び出すには、 SDK コアライブラリと ECS SDK の両方を入手してインストールする 次のいずれかの方法で、Alibaba Cloud .NET SDK をインストールします。

    1. NET SDKからDLL package ダウンロードします。
    2. Visual Studio の Solution Explore でプロジェクトを右クリックし、 [参照] をクリックします。
    3. 表示されたメニューで、 [参照の追加] をクリックします。
    4. 表示されるダイアログボックスで、 [ブラウズ] をクリックします。 ダウンロードした DLL ファイルを選択して、 [確認] をクリックします。
  • プロジェクト参照を追加
    1. 以下のコマンドを実行して GitHub から SDK のソースコードを複製します。
      1. git clone https://github.com/aliyun/aliyun-openapi-net-sdk.git
      複製されたディレクトリで、 aliyun-net-openapi-XXX が付いているフォルダが多くあります。 各フォルダには、NET プロジェクトファイルの \\*.csproj ファイルが 含まれています。 たとえば、 aliyun-net-sdk-ecs.csproj ファイルが aliyun-net-openapi-ecs サブフォルダ配下にあります。
    2. Visual Studio で、ソリューションを右クリックします。
    3. 追加 > 既存のプロジェクトをクリックします。
    4. 表示されたダイアログボックスで、プロジェクトファイル、たとえば、 aliyun-net-sdk-ecs.csproj を選択し、 開く をクリックします。
    5. プロジェクトを右クリックして参照 > 参照の追加をクリックします。

.NET SDK の 使用

次のコード例は、 Alibaba Cloud を使用するための 3 つの主なステップです。NET SDK:

  1. DefaultAcsClient インスタンスを作成して初期化します。
  2. API リクエストを作成してパラメータを設定します。
  3. リクエストを開始してレスポンスを処理します。
    1. using Aliyun.Acs.Core.Profile;
    2. using Aliyun.Acs.Core.Exceptions;
    3. using Aliyun.Acs.Ecs.Model.V20140526;
    4. class TestProgram
    5. {
    6. static void Main(string[] args)
    7. {
    8. // Construct a client for initiating requests
    9. IClientProfile profile = DefaultProfile.GetProfile(
    10. "<your-region-id>",
    11. "<your-access-key-id>",
    12. "<your-access-key-secret>")
    13. DefaultAcsClient client = new DefaultAcsClient(profile);
    14. try
    15. {
    16. // Construct a request
    17. DescribeInstancesRequest request = new DescribeInstancesRequest();
    18. request.PageSize = 10;
    19. // Initiate the request and obtain the response
    20. DescribeInstancesResponse response = client.GetAcsResponse(request);
    21. System.Console.WriteLine(response.TotalCount);
    22. }
    23. catch (ServerException ex)
    24. {
    25. System.Console.WriteLine(ex.ToString());
    26. }
    27. catch (ClientException ex)
    28. {
    29. System.Console.WriteLine(ex.ToString());
    30. }
    31. }
    32. }

SDKの使用

.NET SDKの使用

ここでは、Alibaba Claud .NET SDK をインストールして呼び出す方法を紹介します。

.NET SDK のインストール

Alibaba Cloud .NET SDK のインストールは、次のいずれかの方法で可能です。

  • DLL リファレンスを追加
    1. 『.NET SDK』から DLL パッケージをダウンロードします。
    2. Visual Studio の Solution Explorer でプロジェクトを右クリックし、[リファレンス] をクリックします。
    3. 表示されたメニューで、[リファレンスの追加] をクリックします。
    4. 表示されたダイアログボックスで、[閲覧] をクリックします。 ダウンロードした DLL ファイルを選択し、[確認] をクリックします。
  • プロジェクトリファレンスの追加
    1. 以下のコマンドを実行し、GitHub から SDK のソースコードを複製します。
      1. git clone https://github.com/aliyun/aliyun-openapi-net-sdk.git
      複製されたディレクトリには、 "aliyun-net-openapi-XXX" と付けらた多くのフォルダがあります。 各フォルダには、 .NET プロジェクトファイル (\\*.csproj ファイル) が含まれています。 たとえば、 aliyun-net-openapi-ecs サブフォルダ配下には、 aliyun-net-sdk-ecs.csproj ファイルがあります。
    2. Visual Studio で、ソリューションを右クリックします。
    3. [追加] > [既存プロジェクト]をクリックします。
    4. 表示されたダイアログボックスで、プロジェクトファイルを選択します。たとえば、 aliyun-net-sdk-ecs.csproj を選択し、次に [開く] をクリックします。
    5. プロジェクトを右クリックし、[リファレンス] > [リファレンスの追加]の順に選択します。
資格情報の設定

Alibaba Cloud NET SDK を使用して Alibaba Cloud サービスにアクセスする場合は、認証用の Alibaba Cloud アカウントが必要です。
現在、 .NET SDK は次の認証方法をサポートしています。

  • AccessKey:AccessKey ID を使用
  • STS Token:STS トークンを使用
  • RamRoleArn:RAM アカウントの AssumeRole を使用
  • EcsRamRole:ECS インスタンスの RAM ロールを使用

ここでは、AccessKey を例に資格情報の設定方法を説明します。 アカウントのセキュリティを確保するために、プライマリアカウントの代わりに RAM アカウントを使用することを推奨します。 プライマリアカウントはすべてのクラウドサービスへのフルアクセス権を持ち、 RAM アカウントはプライマリアカウントに認められているアクセス権よりも制限されています。 「AccessKey の作成」の説明に従って AccessKey を作成し、 クライアントの初期化時に、以下のように資格情報を設定します。

注:自身の AccessKey を含むいかなるコードも公開しないでください (GitHub の公開プロジェクトにコードをコミットしないでください)。Alibaba Cloud アカウントが脅威にさらされる可能性があります。

  1. IClientProfile clientProfile = DefaultProfile.GetProfile(
  2. "<your-region-id>", // region ID
  3. "<your-access-key-id>", // AccessKey ID of RAM account
  4. "<your-access-key-secret>"); // AccessKey Secret of RAM account
呼び出しの開始

ここでは、ECS を例として Alibaba Cloud .NET SDK を使用してリクエストを送信する方法を説明します。

  1. デフォルトのクライアントインスタンスを作成
    1. DefaultAcsClient client = new DefaultAcsClient(clientProfile);
  2. リクエストを作成
    リクエストの命名規則は、${apiName}Request です。 ${apiName}は、 DescribeInstances などの API 名です。
    複数のプロダクトの SDK が使用されている場合は、異なるリクエストが同じ名前となることがあります。 パッケージに従ってリクエストを区別します。
    1. DescribeInstancesRequest request = new DescribeInstancesRequest();
    2. request.PageSize = 10;
  3. 呼び出しを開始し、レスポンスを処理
    1. DescribeInstancesResponse response = client.GetAcsResponse(request);
    通常、レスポンス内のすべてのフィールドはレスポンスに逆シリアル化されます。 response.getXXX を呼び出すことでレスポンス内のフィールドを取得できます。
    1. System.Console.WriteLine(response.TotalCount);

エラー処理

サービス側または SDK 側でエラーが発生した場合、 Alibaba Cloud .NET SDK は対応する例外を返します。 これらの例外には、エラーコード (Error Code) やエラーメッセージ (Error Message) を含む詳細なエラー情報が含まれています。
Alibaba Cloud .NET SDK から返された例外を処理する必要はありません 。サービスから返されたエラーのみを処理する必要があります。

  • ServerException は 対応する Alibaba Cloud サービスから返される例外です。
  • ClientException は Alibaba Cloud .NET SDK から返される例外です。

たとえば、次のエラーが発生した場合は、エラーメッセージに従って AccessKey の ID を変更する必要があります。

  1. InvalidAccessKeyId.NotFound : Specified access key is not found.

Alibaba Cloud .NET SDK から返されたクライアントエラーを処理したい場合は、コードを記述するために、次の例をご参照ください。

  1. try
  2. {
  3. CreateInstanceResponse response = client.GetAcsResponse(request);
  4. // Handle the response
  5. // ...
  6. }
  7. catch (ServerException e)
  8. {
  9. // You can add your own error handling logic here
  10. // For example, print the error message
  11. Console.WriteLine("ErrorCode=" + e.ErrorCode);
  12. Console.WriteLine("ErrorMessage=" + e.ErrorMessage);
  13. // If the problem is tricky, you can open a ticket and provide the RequestId to us
  14. Console.WriteLine("ErrorCode=" + e.RequestId);
  15. }
  16. catch (ClientException e)
  17. {
  18. // You can add your own error handling logic here
  19. // For example, print the error message
  20. Console.Writeline("error code :" + e.errorCode;
  21. Console.Writeline("error message :" + e.Message;
  22. }

STS トークンの設定

Alibaba Cloud AccessKey を直接使用してアプリケーションを開発した場合、セキュリティ上のリスクが生じる可能性があります。 アカウントのセキュリティを強化するために、サブアカウントに発行された STS (Security Token Service) トークンを使用して Alibaba Cloud サービスにアクセスできます。

STS トークンの紹介

STS (Security Token Service) は、 Alibaba Cloud アカウント (または RAM ユーザー) に短期間のアクセス制御を提供するクラウドサービスです。 STS を使用して、フェデレーションユーザー (ローカルアカウントシステムによって管理されているユーザー) に期限とアクセス権を指定してアクセス資格情報を発行できます。 フェデレーションユーザーは、 STS の短期間アクセス資格情報を使用して Alibaba Cloud API を直接呼び出す、または Alibaba Cloud コンソールにログインして許可されたリソースを管理することができます。
アクセス資格情報として STS トークンを使用すると、次のような利点があります。

  • AccessKey ID と AccessKey Secret が危険にさらされるリスクが軽減されます。特にモバイルデバイスへのリスクが軽減されます。
  • STS トークンでは柔軟に権限を制御することができます。 RAM のロールに応じて、SLB や ECS などのプロダクトに対してより細かい粒度でアクセス権限を制御できます。

注:ご使用のプロダクトが STS をサポートしていることをご確認ください。

STS トークンの設定

STS トークンを設定するには、次の 2 つの方法があります。

  1. メソッド 1: STS トークンの直接使用
    STS トークンを直接指定できます。 トークンを直接指定した場合、トークンを定期的にアップデートする必要があります。
    1. using System;
    2. using Aliyun.Acs.Core;
    3. using Aliyun.Acs.Core.Auth;
    4. using Aliyun.Acs.Core.Profile;
    5. using Aliyun.Acs.Core.Exceptions;
    6. using Aliyun.Acs.Ecs.Model.V20140526;
    7. class SimpleSTSTokenSample
    8. {
    9. static void Main(string[] args)
    10. {
    11. BasicSessionCredentials credentials = new BasicSessionCredentials(
    12. "<your-access-key-id>",
    13. "<your-access-key-secret>",
    14. "<your-session-token>"
    15. // Create a client instance
    16. IClientProfile profile = DefaultProfile.GetProfile("<your-region-id>");
    17. DefaultAcsClient client = new DefaultAcsClient(profile, credentials);
    18. try
    19. {
    20. // Create an API request and set parameters
    21. DescribeInstancesRequest request = new DescribeInstancesRequest();
    22. request.PageSize = 10;
    23. // Initiate the request and print the handling result
    24. DescribeInstancesResponse response = client.GetAcsResponse(request);
    25. Console.WriteLine("TotalCount: {0}", response.TotalCount);
    26. }
    27. catch (ServerException e)
    28. {
    29. Console.WriteLine(e.ErrorCode);
    30. Console.WriteLine(e.ErrorMessage);
    31. }
    32. catch (ClientException e)
    33. {
    34. Console.WriteLine(e.ErrorCode);
    35. Console.WriteLine(e.ErrorMessage);
    36. }
    37. }
    38. }
    説明
    • region-id: 使用しているリージョン ID。 DescribeRegions API を呼び出すことで、リージョン ID を取得できます。
    • sts-access-key-id、 sts-access-key-secret、sts-session-token: AssumeRole API を呼び出すことで返される資格情報。
  2. メソッド 2: SDK を使用した STS トークンの管理
    Alibaba Cloud を許可するために RAM ロールを指定できます。STS トークンを作成および管理するための NET SDK。
    1. using System;
    2. using Aliyun.Acs.Core;
    3. using Aliyun.Acs.Core.Auth;
    4. using Aliyun.Acs.Core.Profile;
    5. using Aliyun.Acs.Core.Exceptions;
    6. using Aliyun.Acs.Ecs.Model.V20140526;
    7. class UseRoleArnSample
    8. {
    9. static void Main(string[] args)
    10. {
    11. IClientProfile profile = DefaultProfile.GetProfile("<your-region-id>");
    12. BasicCredentials basicCredentials = new BasicCredentials(
    13. "<your-access-key-id>",
    14. "<your-access-key-secret>")
    15. STSAssumeRoleSessionCredentialsProvider provider = new STSAssumeRoleSessionCredentialsProvider(
    16. basicCredentials,
    17. "<your-role-arn>",
    18. profile);
    19. // Create a client instance
    20. DefaultAcsClient client = new DefaultAcsClient(profile, provider);
    21. try
    22. {
    23. // Create an API request and set parameters
    24. DescribeInstancesRequest request = new DescribeInstancesRequest();
    25. request.PageSize = 10;
    26. // Initiate the request and print the handling result
    27. DescribeInstancesResponse response = client.GetAcsResponse(request);
    28. Console.WriteLine("TotalCount: {0}", response.TotalCount);
    29. }
    30. catch (ServerException e)
    31. {
    32. Console.WriteLine(e.ErrorCode);
    33. Console.WriteLine(e.ErrorMessage);
    34. }
    35. catch (ClientException e)
    36. {
    37. Console.WriteLine(e.ErrorCode);
    38. Console.WriteLine(e.ErrorMessage);
    39. }
    40. }
    41. }
    説明
    • ole-arn: ロールリソース記述子。 ロールの詳細は、RAM コンソールから取得できます。
    • role-session-name: 一時的なロール名。 一時的な ID を作成するために AssumeRole API を呼び出すことができます。 このメソッドでは、一時的 ID を作成後、role-session-name パラメーターとして、RoleSessionName パラメーターに設定した値を使用することができます。

ECS インスタンス RAM ロールの設定

コード例
  1. using Aliyun.Acs.Core;
  2. using Aliyun.Acs.Core.Auth;
  3. using Aliyun.Acs.Core.Exceptions;
  4. using Aliyun.Acs.Core.Profile;
  5. using Aliyun.Acs.Ecs.Model.V20140526;
  6. class NoAKAccessSample
  7. {
  8. static void Main(string[] args)
  9. {
  10. // Construct a client instance for initializing requests
  11. DefaultProfile profile = DefaultProfile.GetProfile("<your-region-id>");
  12. InstanceProfileCredentialsProvider provider = new InstanceProfileCredentialsProvider(
  13. "<your-role-name>");
  14. DefaultAcsClient client = new DefaultAcsClient(profile, provider);
  15. try
  16. {
  17. // Construct a request
  18. DescribeInstancesRequest request = new DescribeInstancesRequest();
  19. request.PageSize = 10;
  20. // Initiate the request and obtain the response
  21. DescribeInstancesResponse response = client.GetAcsResponse(request);
  22. System.Console.WriteLine(response.TotalCount);
  23. }
  24. catch (ServerException ex)
  25. {
  26. System.Console.WriteLine(ex.ToString());
  27. }
  28. catch (ClientException ex)
  29. {
  30. System.Console.WriteLine(ex.ToString());
  31. }
  32. }
  33. }

CommonRequest の使用

Alibaba Cloud 製品が API 用の SDK を提供していない場合は、汎用 API (CommonRequest) を使用して製品 API を呼び出すことができます。 CommonRequest 呼び出しメソッドを使用して、 任意の API を呼び出すことができます。

例: RPC API を呼び出す

次のコードは、 CommonRequest 呼び出しメソッドを使用してDescribeInstanceStatus APIを呼び出す方法を示しています。

  1. using Aliyun.Acs.Core;
  2. using Aliyun.Acs.Core.Exceptions;
  3. using Aliyun.Acs.Core.Profile;
  4. class Sample
  5. {
  6. static void Main(string[] args)
  7. {
  8. // Construct a client instance for initializing requests
  9. IClientProfile profile = DefaultProfile.GetProfile(
  10. "<your-region-id>",
  11. "<your-access-key-id>",
  12. "<your-access-key-secret>")
  13. DefaultAcsClient client = new DefaultAcsClient(profile);
  14. try
  15. {
  16. // Construct a request
  17. CommonRequest request = new CommonRequest();
  18. request.Domain = "ecs.aliyuncs.com";
  19. request.Version = "2014-05-26";
  20. // Because the API is an RPC API, you must specify the value of the ApiName (Action) field.
  21. request.Action = "DescribeInstanceStatus";
  22. request.AddQueryParameters("PageNumber", "1");
  23. request.AddQueryParameters("PageSize", "30");
  24. // Initiate the request and obtain the response
  25. CommonResponse response = client.GetCommonResponse(request);
  26. System.Console.WriteLine(response.Data);
  27. }
  28. catch (ServerException ex)
  29. {
  30. System.Console.WriteLine(ex.ToString());
  31. }
  32. catch (ClientException ex)
  33. {
  34. System.Console.WriteLine(ex.ToString());
  35. }
  36. }
  37. }
例: RESTful API を呼び出す

次のコードは、 CommonRequest 呼び出しメソッドを使用して GetClusterList API を呼び出す方法を示しています。

  1. using Aliyun.Acs.Core;
  2. using Aliyun.Acs.Core.Exceptions;
  3. using Aliyun.Acs.Core.Profile;
  4. class Sample
  5. {
  6. static void Main(string[] args)
  7. {
  8. // Construct a client instance for initializing requests
  9. IClientProfile profile = DefaultProfile.GetProfile(
  10. "<your-region-id>",
  11. "<your-access-key-id>",
  12. "<your-access-key-secret>");
  13. DefaultAcsClient client = new DefaultAcsClient(profile);
  14. try
  15. {
  16. // Construct a request
  17. CommonRequest request = new CommonRequest();
  18. request.Domain = "cs.aliyuncs.com";
  19. request.Version = "2015-12-15";
  20. // Because the API is a RESTful API, you must specify the value of the UriPattern field.
  21. request.UriPattern = "/clusters";
  22. // Initiate the request and obtain the response
  23. CommonResponse response = client.GetCommonResponse(request);
  24. System.Console.WriteLine(response.Data);
  25. }
  26. catch (ServerException ex)
  27. {
  28. System.Console.WriteLine(ex.ToString());
  29. }
  30. catch (ClientException ex)
  31. {
  32. System.Console.WriteLine(ex.ToString());
  33. }
  34. }
  35. }

エラーとトラブルシューティング

ここでは、Alibaba Cloud NET SDK 使用時に発生する可能性がある一般的なエラーを紹介します。発生事例のあるこれらの一般的なエラーについて、考えられる原因と解決策を記載します。

エラーコード 原因 解決策
SDK.InvalidRegionId SDK は、指定されたリージョンで呼び出されたプロダクトのエンドポイントを自動的に取得することはできません。 呼び出すサービスの正確なエンドポイントを指定してください。 エンドポイントはプロダクトの API ドキュメントから検索することができます。
InvalidAccessKeyId.NotFound AccessKey ID が無効です。 正しい AccessKey ID を入力してください。
SDK.ConnectionReset リクエストの開始時にエンドポイントに接続できません。 ネットワークが利用可能であることを確認してください。
SDK.InvalidProfile DefaultAcsClient の初期化時に指定した DefaultAcsClient パラメーターが無効です。 指定した DefaultProfile パラメーターオブジェクトが正常に初期化され、対応するパラメーターで設定されていることをご確認ください。
SDK.SessionTokenExpired DefaultAcsClient の初期化時に指定した DefaultAcsClient パラメーターが無効です。 SessionToken パラメーターが有効期間(通常は 1 時間)内であることをご確認ください。
SignatureDoesNotMatch 指定した SessionToken は無効か、または有効期限が切れています。 指定した DefaultProfile パラメーターオブジェクトが正常に初期化され、対応するパラメーターで設定されていることをご確認ください。
SDK.InvalidProfile AccessKey シークレットが AccessKey ID と一致しません。 AccessKey Secret が有効であることをご確認ください。