Go SDK

プロダクト紹介

Go SDKとは

Alibaba Cloud Go SDK (Software Development Kit) を使用すると、 ECS (Elastic Compute Service) 、SLB (Server Load Balancer) 、CloudMonitor などの Alibaba Cloud サービスにアクセスできます。 リクエストの署名や作成などの API 関連のタスクを処理することなく、 Alibaba Cloud サービスにアクセスできます。 ここでは Alibaba Cloud Go SDK を取得して呼び出す方法を紹介します。

環境の準備

  • Alibaba Cloud Go SDK を使用するには、 Alibaba Cloud アカウントと AccessKey が必要です。 AccessKey は AcsClient を初期化するときに必要です。 Alibaba Cloud コンソールの AccessKey コンソール で AccessKey を作成することができます。
  • Alibaba Cloud Go SDK を使用してプロダクトの API にアクセスするには、必要に応じて、まず Alibaba Cloud コンソールでプロダクトをアクティブに必要があります。

Go SDK のインストール

以下のコマンドを実行して Alibaba Cloud Go SDK を インストールします。

  1. glide get github.com/aliyun/alibaba-cloud-sdk-go

Go SDK の使用

次のコード例は、 Alibaba Cloud Go SDK を使用するための 3 つの主なステップとなります。

  1. クライアントを作成します。
  2. API リクエストを作成してパラメータを設定します。
  3. リクエストを開始して例外を処理します。
  1. package main
  2. import (
  3. "github.com/aliyun/alibaba-cloud-sdk-go/services/ecs"
  4. "github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
  5. "fmt"
  6. func main() {
  7. // Create an ECS client
  8. ecsClient, err := ecs.NewClientWithAccessKey(
  9. "<Your-region-ID>", // your region ID
  10. "<Your-access-key-ID>", // AccessKey ID
  11. "<your-access-key-secret>") // AccessKey Secret
  12. if err ! = nil {
  13. // Handle exceptions
  14. panic(err)
  15. // Create an API request and set parameters
  16. request := ecs.CreateDescribeInstancesRequest()
  17. / Set the request.PageSize to "10"
  18. request.PageSize = requests.NewInteger(10)
  19. // Initiate the request and handle exceptions
  20. response, err := ecsClient.DescribeInstances(request)
  21. if err ! = nil {
  22. // Handle exceptions
  23. panic(err)
  24. fmt.Println(response)

ユーザーガイド

Go SDK の使用

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

インストール

Alibaba Cloud Go SDK は Go 1.7 以降をサポートしています。 次の方法で Go SDK のインストールが可能です。

  • Glide の使用 (推奨)
    1. glide get github.com/aliyun/alibaba-cloud-sdk-go
  • govendor の使用
    インストールするには次のコマンドを実行します。 実行します。
    1. go get -u github.com/aliyun/alibaba-cloud-sdk-go/sdk

資格情報の設定

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

  • AccessKey:AccessKey ID および Secret を使用
  • STS Token:STS トークンを使用
  • RamRoleArn:RAM アカウントの AssumeRole を使用
  • EcsRamRole:ECS インスタンスの RAM ロールを使用
  • RsaKeyPair:RSA 鍵ペアを使用 (日本のサイトでのみサポート)

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

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

  1. // Create the ecsClient instance
  2. ecsClient, err := ecs.NewClientWithAccessKey(
  3. "<your-region-id>", // your region ID
  4. "<your-access-key-id>", // your AccessKey ID
  5. "<your-access-key-secret>") // your AccessKey Secret

カスタム Config または AccessKey 以外の資格情報を使用する場合は、資格情報を保存するために最初に Credential オブジェクトを作成し、クライアントの初期化時に Credential オブジェクトを送信します。

  1. // Customize config
  2. config := NewConfig()
  3. // Create a credential object
  4. credential := &credentials.BaseCredential{
  5. AccessKeyId: "<your-access-key-id>",
  6. AccessKeySecret: "<your-access-key-secret>",
  7. // Initiate the client
  8. client, err := NewClientWithOptions("cn-hangzhou", config, credential)

サービスの呼び出し

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

  1. Alibaba Cloud Go SDK をインポート
    1. import github.com/aliyun/alibaba-cloud-sdk-go/services/ecs
  2. ECS クライアントを作成
    1. ecsClient := ecs.NewClientWithAccessKey(
    2. "<your-region-id>",
    3. "<your-access-key-id>",
    4. "<your-access-key-secret>")
  3. xxx.CreateXXXRequest メソッドを使用してリクエストを作成し、関連するリクエストパラメーターに値を割り当ててください。
    このメソッドの命名規則は $ {service} Create${apiName}Request です。
    • ${service}: ecs、oss、slb などの小文字で表されたプロダクト名
    • ${apiName}: DescribeInstanceAttribute などの API 名
    1. request := ecs.CreateDescribeInstanceAttributeRequest()
    2. request.InstanceId = ""
  4. 呼び出しの開始
    1. response, err := ecsClient.DescribeInstanceAttribute(request)
  5. 応答の処理
    返されたすべての属性は、応答へ逆シリアル化されます。response.getXXX を直接呼び出して応答属性を取得することが可能です。
    1. instanceStatus := response.Status

    (err nil) エラーが発生した、または元の HTTP レスポンスを取得したい場合、 オリジナルデータは次のようにして入手できます。


    1. // Obtain the original http response, and the response type is *http.Response
    2. httpResponse := response.GetOriginHttpResponse()
    3. // Obtain the status code of the original http response, and the response type is int
    4. statusCode := response.GetHttpStatus()
    5. // Obtain the header of the original http response, and the response type is map[string][]string
    6. headers := response.GetHttpHeaders()
    7. // Obtain the content of the original http response, and the response type is []byte
    8. contentBytes := response.GetHttpContentBytes()
    9. // Obtain the content of the original http response and transcode it to string according to UTF-8, and the response type is string.
    10. contentString := response.GetHttpContentString()

設定のカスタマイズ

サポートしているカスタム設定については、以下の「サポート対象のカスタム設定」をご参照ください。

設定方法

Alibaba Cloud Go SDK の設定モジュールを使用して設定をカスタマイズできます。

  1. config := NewConfig().
  2. WithEnableAsync(true).
  3. WithGoRoutinePoolSize(5).
  4. WithMaxTaskQueueSize(1000)
  5. client, err := ecs.NewClientWithOptions("<region-id>", config, credential)

注:Alibaba Cloud Go SDK の config モジュールは、次の呼び出しメソッドをサポートしていません。

  1. config := &Config{EnableAsync: true,}

サポート対象のカスタム設定

サポート対象のカスタム設定については、次の表をご参照ください。

設定項目 デフォルト値 説明
AutoRetry true 自動再試行を有効にするかどうか。
MaxRetryTime 3 再試行の最大回数は 10 回です。 自動再試行が有効になっている場合、 1 回の呼び出しの最大消費時間は次のとおりです。Timeout (MaxRetryTime + 1)
Timeout 10time.Second 接続の確立、リダイレクト、応答の読み取りを含む、フルリンクタイムアウト。 値がゼロの場合、タイムアウトは発生しません。
HttpTransport nil net/http.client の設定を有効にします。 永続的な接続など、 http.client を設定することができます。
EnableAsync false 非同期呼び出しを有効にするかどうか。
MaxTaskQueueSize 1000 この設定は、 EnableAsync=true の場合にのみ有効です。 キューがいっぱいになると、新しい呼び出しが輻輳します。
GoRoutinePoolSize 5 この設定は、 EnableAsync=true の場合にのみ有効です。

エラー処理

Alibaba Cloud Go SDK は サービス側または SDK 側でエラーが発生した場合は、対応する例外を返します。 これらの例外には、 sdk.errors 配下の ClientErrorServerError などの詳細なエラー情報が含まれています。 これらのエラーは Go エラー API に準拠しているため、 Alibaba Cloud Go SDK から返されたエラーは Go エラーと同じように処理することができます。

ClientError

SDK の呼び出しでエラーが発生して自動的に処理できない場合、 SDK は ClientError を返します。
次のコードを追加して、 ClientError のエラーを特定して取得できます。

  1. response, err := ecsClient.DescribeInstances(request)
  2. if clientError, ok := err.(*errors.ClientError); ok{
  3. // Obtain the error code
  4. clientError.ErrorCode()
  5. // Obtain the error description
  6. clientError.Message()
  7. // Obtain the original error (may be nil)
  8. clientError.OriginError()

ServerError

サーバーサイドからエラーメッセージが返される場合、 SDK はそのレスポンスを ServerError にラップして返します。

注:その場合でも、レスポンスから元の HTTP レスポンスを取得することができます。

次のコードを使用して、 サーバエラー および レスポンスでのエラー情報を特定して取得できます。

  1. response, err := ecsClient.DescribeInstances(request)
  2. if serverError, ok := err.(*errors.ServerError); ok{
  3. // Obtain the error code
  4. serverError.ErrorCode()
  5. // Obtain the error description
  6. serverError.Message()
  7. // Obtain the original http response
  8. response.GetOriginHttpResponse()

非同期呼び出し

Go 言語の同時特性により、SDK の同時要求はアプリケーション層で制御することを推奨します。 使用を容易にするために、Alibaba Cloud Go SDK は直接使用できる同時呼び出し方法を提供しています。 関連する同時実行管理は SDK 内で実現されています。

SDKクライアントの同時実行機能の有効化

以下の例では、Credential オブジェクトを使用し、ユーザーの資格情報を設定します。

  1. // The maximum number of concurrent connections
  2. poolSize := 10
  3. // The maximum number of cacheable requests
  4. maxTaskQueueSize := 10000
  5. // Enable the asynchronous feature when creating a client
  6. config := sdk.NewConfig().
  7. WithEnableAsync(true).
  8. WithGoRoutinePoolSize(poolSize).  // Optional, the default value is 5
  9. WithMaxTaskQueueSize(maxTaskQueueSize) // Optional, the default value is 1,000
  10. // Use the custom configuration to initiate the client
  11. ecsClient, err := ecs.NewClientWithOptions("<your-region-id>", config, credential)
  12. // Or enable the asynchronous feature after initiating the client
  13. client.EnableAsync(poolSize, maxTaskQueueSize)

非同期呼び出しの開始

次の 2 つの方法で、非同期呼び出しを行うことができます。

    1. チャネルを戻り値として使用
      1. // this will not block
      2. responseChannel, errChannel := client.FooWithChan(request)
      3. // this will block
      4. response := <-responseChannel
      5. err = <-errChanne

  1. コールバックの使用
    1. // this will not block
    2. blocker := client.FooWithCallback(request, func(response *FooResponse, err error) {
    3. // handle the response and err
    4. }
    5. )
    6. // The blocker is (chan int) and is used for controlling synchronization. The action succeeds when the return value is one, and fails when the return value is zero.
    7. // When <-blocker returns zero and the action fails, the error is transmitted to callback through err.
    8. // This will block
    9. result := <-blocker

CommonRequest の使用

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

例: RPC API を呼び出す

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

  1. package main
  2. import (
  3. "github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
  4. "github.com/aliyun/alibaba-cloud-sdk-go/sdk"
  5. "fmt"
  6. func main() {
  7. client, err := sdk.NewClientWithAccessKey("cn-hangzhou", "{your_access_key_id}", "{your_access_key_id}")
  8. if err ! = nil {
  9. panic(err)
  10. request := requests.NewCommonRequest()
  11. request.Domain = "ecs.aliyuncs.com"
  12. request.Version = "2014-05-26"
  13. // Because the API is an RPC API, you must specify the value of the ApiName (Action) field.
  14. request.ApiName = "DescribeInstanceStatus"
  15. request.QueryParams["PageNumber"] = "1"
  16. Request. queryparams ["pagesize"] = "30"
  17. response, err := client.ProcessCommonRequest(request)
  18. if err ! = nil {
  19. panic(err)
  20. fmt.Print(response.GetHttpContentString())

例: RESTful API を呼び出す

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

  1. package main
  2. import (
  3. "github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
  4. "github.com/aliyun/alibaba-cloud-sdk-go/sdk"
  5. "fmt"
  6. func main() {
  7. client, err := sdk.NewClientWithAccessKey("cn-hangzhou", "{your_access_key_id}", "{your_access_key_id}")
  8. if err ! = nil {
  9. panic(err)
  10. request := requests.NewCommonRequest()
  11. request.Domain = "cs.aliyuncs.com"
  12. request.Version = "2015-12-15"
  13. //  Because the API is a RESTful API, you must specify the value of the PathPattern field.
  14. request.PathPattern = "/clusters"
  15. response, err := client.ProcessCommonRequest(request)
  16. if err ! = nil {
  17. panic(err)
  18. fmt.Print(response.GetHttpContentString())

ECS インスタンスへの 非 AK アクセスを実現するための RamRole 設定

    • カスタム設定を使用しない例
      1. // If you do not need to customize the configuration, we provide a shortcut to build a client
      2. client, err = ecs.NewClientWithEcsRamRole("region-id", "role-name")

  • カスタム設定を使用する例
    1. // If you need to customize the config, you can use the following codes to build a client
    2. config := sdk.NewConfig(). WithEnableAsync(true)
    3. // Create the credential object
    4. credential := credentials.NewEcsRamRoleCredential("role-name")
    5. // Initialize the client
    6. client, err := ecs.NewClientWithOptions("region-id", config, credential)

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. // If you do not need to customize the config, we provide a shortcut to build a client
        2. client, err = ecs.NewClientWithStsToken("region-id", "sts-access-key-id",
        3. "sts-access-key-secret", "sts-session-token")
      • カスタム設定使用
        1. // If you need to customize the config, you can use the following codes to build a client
        2. config := sdk.NewConfig(). WithEnableAsync(true)
        3. // Create the credential object
        4. credential := credentials.NewEcsRamRoleCredential("role-name")
        5. // Initialize the client
        6. client, err := ecs.NewClientWithOptions("region-id", config, credential)
        説明
        • region-id: 使用しているリージョン ID。 DescribeRegions API を呼び出すことで、リージョン ID を取得できます。
        • sts-access-key-id、 sts-access-key-secret、sts-session-token: AssumeRole API を呼び出すことで返される資格情報。

  1. メソッド 2: SDK を使用した STS トークンの管理
    新しい NewClientWithRamRoleArn オブジェクトを作成し、Alibaba Cloud Go SDK で STS トークンの作成および管理することができます。
    • カスタム設定不使用
      1. // If you do not need to customize the config, we provide a shortcut to build a client
      2. client, err = ecs.NewClientWithRamRoleArn("region-id", "sts-access-key-id",
      3. "sts-access-key-secret", "role-arn", "session-role-name")
    • カスタム設定使用
      1. // If you need to customize the config, you can use the following codes to build a client
      2. Config: = SDK. newconfig ()
      3. // Create the credential object
      4. credential := credentials.NewRamRoleArnCredential("sts-access-key-id",
      5. "sts-access-key-secret", "role-arn", "role-session-name")
      6. // Initialize the client
      7. client, err := ecs.NewClientWithOptions("region-id", config, credential)
      説明
      • role-arn: ロールリソース記述子。 ロールの詳細は、RAM コンソールから取得できます。
      • role-session-name: 一時的なロール名。 一時的な ID を作成するために AssumeRole API を呼び出すことができます。 このメソッドでは、一時的 ID を作成後、role-session-name パラメーターとして、RoleSessionName パラメーターに設定した値を使用することができます。

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

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

エラーコード エラー情報 原因 解決策
SDK.CanNotResolveEndpoint エンドポイントを解決できません。ユーザーガイドをご確認ください。 SDK は、指定されたリージョンで呼び出されたプロダクトのエンドポイントを自動的に取得することはできません。 提供されたリージョン ID とエンドポイントが正確かご確認ください。 以下のコードを実行して、エンドポイントを設定します。 request.Domain = "<endpoint>"
SDK.JsonUnmarshalError 応答のマーシャリング解除に失敗しましたが、次の方法でデータを取得できます。 response.GetHttpStatusCode() and response.GetHttpContentString() SDK レスポンスのデシリアライゼーションに失敗しました。 ほとんどの場合、 SDK が受け取るレスポンス構造が API メタデータに準拠していないためです。 フィールドがマッチしていない、またはフォーマットが正しくないことなどが考えられます。 下記の解決策を ご参照ください
SDK.TimeoutError リクエストが 4 回タイムアウトしました (再試行 3 回)。 しきい値を少し上げてください。 リクエストはタイムアウトし、すべての再試行は失敗しました。
  • リージョンをまたいだ呼び出しやネットワーク低品質などの場合では、タイムアウトまたは最大再試行回数を増やすことを推奨します。
  • 問題が解決せず、ネットワーク品質が良好であることが確認されている場合は、チケットを起票し、サービスセンターへお問い合わせください。
SDK.AsyncFunctionNotEnabled クライアントの非同期機能が有効になっていません。 ‘client.EnableAsync()’ を起動してください。 非同期リクエスト切り替えが有効になっていない場合は、非同期 API が呼び出されます。 非同期機能を有効にします。 詳しくは、「非同期呼び出し」をご参照ください。

解決策

SDK のデシリアライゼーション失敗を無視し、オリジナルの HTTP レスポンスを抽出して、レスポンス属性を取得します。

注:Alibaba Go SDK には JMESPath との依存関係があります。 したがって、レスポンスコンテンツが JSON 形式の場合は、 JMESPath を直接使用してレスポンスを解析できます。

  1. response, err := client.CreateInstance(request)
  2. if err ! = nil {
  3. // Handle exceptions
  4. if clientErr, isClientErr := err.(*errors.ClientError); isClientErr {
  5. if clientErr.ErrorCode() == errors.JsonUnmarshalErrorCode {
  6. // You can respectively obtain the data in the original response through our encapsulate methods.
  7. // The http status code in the response, type: int
  8. statusCode := response.GetHttpStatus()
  9. // The http head in the response, type: map[string][]string
  10. responseHeader := response.GetHttpHeaders()
  11. // The body content in the response, type: []byte
  12. responseBytes := response.GetHttpContentBytes()
  13. // The body content in the response, type: string, equivalent to string(response.GetHttpContentBytes())`
  14. responseContent := response.GetHttpContentString()
  15. // You can also directly obtain the original response, type: net/http.Response
  16. httpResponse := response.GetOriginHttpResponse()
  17. }