aws-sdk-go - Go プログラミング言語用の AWS SDK。

(AWS SDK for the Go programming language.)

Created at: 2014-12-05 13:29:41
Language: Go
License: Apache-2.0

AWS SDK for Go

API リファレンス https://gitter.im/aws/aws-sdk-go でチャットに参加する ビルドの状態 Apache V2 ライセンス

aws-sdk-go は、Go プログラミング言語の公式 AWS SDK です。

リリースノートをご覧ください SDK に追加された最新のバグ修正、更新、および機能に関する情報。

AWS SDK for Go V2 (v2) の一般提供を発表しました。v2 SDK ソースは https://github.com/aws/aws-sdk-go-v2 で入手できます。AWS SDK for Go V2 の使用を開始するには、v2 SDK の開発者ガイドを確認するか、すでにバージョン 1 を使用している場合は移行ガイドを確認してください。

ジャンプ先:

はじめ

装着

SDK を取得してワークスペースに追加するために使用します。 プロジェクトのGoモジュールの依存関係。

go get
GOPATH

go get github.com/aws/aws-sdk-go

SDK を更新するには、SDK の最新バージョンを取得するために使用します。

go get -u

go get -u github.com/aws/aws-sdk-go

依存 関係

SDK には、 です。SDK の依存関係のメタデータは、Go モジュール ファイルまたは Dep ファイル にあります。

vendor
go.mod
Gopkg.toml

Go モジュール

Goモジュールを使用している場合、デフォルトで最新のタグが付けられます SDK のリリース バージョン。SDK の特定のリリース バージョンを取得するには、コマンドで使用します。

go get
@<tag>
go get

go get github.com/aws/aws-sdk-go@v1.15.77

最新の SDK リポジトリの変更を取得するには、.

@latest

go get github.com/aws/aws-sdk-go@latest

囲碁1.5

ベンダーを有効にせずに Go 1.5 を使用している場合、()、 SDK を取得するときに、その依存関係を取得するために使用する必要があります。

GO15VENDOREXPERIMENT=1
...

go get github.com/aws/aws-sdk-go/...

これには引き続きフォルダが含まれます。フォルダは削除できます ご使用の環境で使用されていない場合。

vendor
vendor

rm -rf $GOPATH/src/github.com/aws/aws-sdk-go/vendor

簡単な例

完全な SDK の例

この例は、S3にファイルをアップロードする完全な作業Goファイルを示しています コンテキストパターンを使用して、キャンセルするタイムアウトロジックを実装します 時間がかかりすぎる場合は要求してください。この例では、セッションの使用方法を強調しています。 サービスクライアントを作成し、要求を行い、エラーを処理し、 応答。

  package main

  import (
  	"context"
  	"flag"
  	"fmt"
  	"os"
  	"time"

  	"github.com/aws/aws-sdk-go/aws"
  	"github.com/aws/aws-sdk-go/aws/awserr"
  	"github.com/aws/aws-sdk-go/aws/request"
  	"github.com/aws/aws-sdk-go/aws/session"
  	"github.com/aws/aws-sdk-go/service/s3"
  )

  // Uploads a file to S3 given a bucket and object key. Also takes a duration
  // value to terminate the update if it doesn't complete within that time.
  //
  // The AWS Region needs to be provided in the AWS shared config or on the
  // environment variable as `AWS_REGION`. Credentials also must be provided
  // Will default to shared config file, but can load from environment if provided.
  //
  // Usage:
  //   # Upload myfile.txt to myBucket/myKey. Must complete within 10 minutes or will fail
  //   go run withContext.go -b mybucket -k myKey -d 10m < myfile.txt
  func main() {
  	var bucket, key string
  	var timeout time.Duration

  	flag.StringVar(&bucket, "b", "", "Bucket name.")
  	flag.StringVar(&key, "k", "", "Object key name.")
  	flag.DurationVar(&timeout, "d", 0, "Upload timeout.")
  	flag.Parse()

  	// All clients require a Session. The Session provides the client with
 	// shared configuration such as region, endpoint, and credentials. A
 	// Session should be shared where possible to take advantage of
 	// configuration and credential caching. See the session package for
 	// more information.
  	sess := session.Must(session.NewSession())

 	// Create a new instance of the service's client with a Session.
 	// Optional aws.Config values can also be provided as variadic arguments
 	// to the New function. This option allows you to provide service
 	// specific configuration.
  	svc := s3.New(sess)

  	// Create a context with a timeout that will abort the upload if it takes
  	// more than the passed in timeout.
  	ctx := context.Background()
  	var cancelFn func()
  	if timeout > 0 {
  		ctx, cancelFn = context.WithTimeout(ctx, timeout)
  	}
  	// Ensure the context is canceled to prevent leaking.
  	// See context package for more information, https://golang.org/pkg/context/
	if cancelFn != nil {
  		defer cancelFn()
	}

  	// Uploads the object to S3. The Context will interrupt the request if the
  	// timeout expires.
  	_, err := svc.PutObjectWithContext(ctx, &s3.PutObjectInput{
  		Bucket: aws.String(bucket),
  		Key:    aws.String(key),
  		Body:   os.Stdin,
  	})
  	if err != nil {
  		if aerr, ok := err.(awserr.Error); ok && aerr.Code() == request.CanceledErrorCode {
  			// If the SDK can determine the request or retry delay was canceled
  			// by a context the CanceledErrorCode error code will be returned.
  			fmt.Fprintf(os.Stderr, "upload canceled due to timeout, %v\n", err)
  		} else {
  			fmt.Fprintf(os.Stderr, "failed to upload object, %v\n", err)
  		}
  		os.Exit(1)
  	}

  	fmt.Printf("successfully uploaded file to %s/%s\n", bucket, key)
  }

SDK のパッケージの概要

SDK は、SDK コアとサービス クライアントの 2 つの主要コンポーネントで構成されています。 SDK コアパッケージはすべて、のルートにある aws パッケージで入手できます。 SDK です。サポートされている AWS サービスの各クライアントは、独自のクライアント内で使用できます。 SDK のルートにあるサービス フォルダーの下にパッケージを配置します。

  • aws - SDKコアは、コンフィグ、ロガーなどの一般的な共有タイプを提供します。 APIパラメータの操作を容易にするユーティリティ。

    • awserr - SDK がすべてに使用するエラーインターフェイスを提供します。 SDK の処理中に発生するエラー。これにはサービス API が含まれます 応答エラーも同様です。エラータイプは、コードとメッセージで構成されます。 SDK の返されたエラータイプを awserr にキャストします。エラーとコードの呼び出し メソッドを使用して、返されたエラーを特定のエラーコードと比較します。パッケージの RequestID など、抽出できる追加の値に関するドキュメント。

    • 資格情報 - 種類と組み込みの資格情報プロバイダーを提供します SDK は、API リクエストを行うための AWS 認証情報を取得するために使用します。 このフォルダーの下には、次のような追加の資格情報プロバイダーも入れ子になっています。 IAM ロールを引き受けるための stscreds、および EC2 インスタンスロールの ec2rolecreds を引き受けます。

    • エンドポイント - SDK の AWS リージョンとエンドポイントのメタデータを提供します。 これを使用して、どのサービスなどのAWSサービスエンドポイント情報を検索します はリージョン内にあり、サービスはどのリージョンにあるか。定数も提供されています すべてのリージョン識別子 (例: "us-west-2" の場合は UsWest2RegionID)。

    • session - 初期デフォルト設定とロードを提供します。 環境や共有などの外部ソースからの構成 資格情報ファイル。

    • request - SDK の API 要求の送信と再試行ロジックを提供します。 本パッケージには、独自のリクエストを定義するためのユーティリティも含まれています。 再試行し、SDK が要求を処理する方法を構成します。

  • サービス - AWS のサービスのクライアント。SDK でサポートされているすべてのサービスは次のとおりです。 このフォルダの下にあります。

SDK の AWS サービスクライアントの使用方法

SDK には、要求を行うために使用できる Go タイプとユーティリティが含まれています。 AWS のサービス API。SDK のルートにあるサービス フォルダー内には、 SDK がサポートする AWS サービスごとのパッケージ。すべてのサービス クライアントは、作成と使用の共通のパターンに従います。

AWSサービスのクライアントを作成するときは、最初にセッションが必要です 構築された値。セッションは、共有可能な共有構成を提供します サービスクライアント間。サービスクライアントが作成されると、渡すことができます AWSを介した追加設定で。構成をオーバーライドする構成タイプ カスタムでサービスクライアントインスタンスを作成するためにセッションで提供されます 構成。

サービスのクライアントが作成されたら、それを使用してAPIリクエストを行うことができます AWS のサービス。これらのクライアントは、同時に使用しても安全です。

SDK の構成

AWS SDK for Go では、次のようなサービスクライアントの設定を構成できます。 ログレベルと再試行の最大数として。ほとんどの設定はオプションです。 ただし、サービス クライアントごとに、リージョンと資格情報を指定する必要があります。 SDK はこれらの値を使用して、正しい AWS リージョンにリクエストを送信し、署名します。 正しい資格情報を使用した要求。これらの値は、の一部として指定できます。 セッションの、または環境変数として。

詳細については、SDK の構成ガイドを参照してください。

Session の使用方法の詳細については、セッションパッケージのドキュメントを参照してください。 を SDK に置き換えます。

設定の詳細については、aws パッケージの Config タイプを参照してください。 オプション。

クレデンシャルの設定

SDK を使用する場合、通常、認証には AWS 認証情報が必要です。 AWS のサービスを使用します。SDK は、これらをサポートする複数の方法をサポートしています。 資格 情報。デフォルトでは、SDK は資格情報を自動的に取得します。 既定の資格情報チェーン。詳細については、セッションパッケージを参照してください。 このチェーンで、それを構成する方法。資格情報の共通項目 チェーンは次のとおりです。

  • 環境資格情報 - 有用な環境変数のセット 特定のロールに対してサブプロセスが作成されるとき。

  • 共有認証情報ファイル (~/.aws/credentials) - このファイルには、 プロファイル名に基づく資格情報で、ローカル開発に役立ちます。

  • EC2 インスタンスロールの認証情報 - EC2 インスタンスロールを使用して認証情報を割り当てる EC2 インスタンスで実行されているアプリケーション。これにより、管理する必要がなくなります 運用環境の資格情報ファイル。

資格情報は、構成の資格情報を設定することで、コードでも構成できます。 値をカスタム プロバイダーに追加するか、 SDK を使用して既定の資格情報チェーンをバイパスし、カスタム資格情報チェーンを使用します。これは 特定のセットのみを使用するようにSDKに指示する場合に役立ちます 資格情報またはプロバイダー。

この例では、IAM ロール "myRoleARN" を引き受けるための認証情報プロバイダーを作成します。 API リクエストにそのロールを使用するように S3 サービスクライアントを設定します。

  // Initial credentials loaded from SDK's default credential chain. Such as
  // the environment, shared credentials (~/.aws/credentials), or EC2 Instance
  // Role. These credentials will be used to to make the STS Assume Role API.
  sess := session.Must(session.NewSession())

  // Create the credentials from AssumeRoleProvider to assume the role
  // referenced by the "myRoleARN" ARN.
  creds := stscreds.NewCredentials(sess, "myRoleArn")

  // Create service client value configured for credentials
  // from assumed role.
  svc := s3.New(sess, &aws.Config{Credentials: creds})

資格情報の詳細については、資格情報パッケージのドキュメントを参照してください。 SDK に含まれているプロバイダー、および SDK の使用方法をカスタマイズする方法 資格 情報。

SDK は共有設定ファイル (~/.aws/config) をサポートしています。これ サポートは、環境変数 "AWS_SDK_LOAD_CONFIG=1" を設定することで有効にできます。 または、を介してセッションを作成するときにコードで機能を有効にします。 オプションの SharedConfigState パラメーター。

  sess := session.Must(session.NewSessionWithOptions(session.Options{
      SharedConfigState: session.SharedConfigEnable,
  }))

AWS リージョンの設定

資格情報に加えて、SDK のリージョンを指定する必要があります は、AWS API リクエストを行うために使用します。SDK では、リージョンを指定できます。 環境変数を使用するか、セッションまたは サービスクライアントが作成されます。コードで指定された最後の値は、領域が優先されます は複数の方法で指定されます。

環境変数を使用してリージョンを設定するには、「AWS_REGION」を SDK で使用するリージョン。このメソッドを使用して領域を設定すると、 追加の必要なく複数のリージョンでアプリケーションを実行できるようにする アプリケーション内のコードを使用して、リージョンを選択します。

AWS_REGION=us-west-2

エンドポイント パッケージには、SDK が認識するすべてのリージョンの定数が含まれています。ザ 値にはすべてリージョン ID のサフィックスが付きます。これらの値は、 領域文字列を手動で入力する必要性を減らします。

セッションでリージョンを設定するには、aws パッケージの Config 構造体パラメータを使用します。 セッションからサービスクライアントを作成するAWSリージョンへのリージョン 使う。これは、複数のサービスクライアントを作成する場合に役立ちます。 すべてのクライアントは、同じリージョンに対して API リクエストを行います。

  sess := session.Must(session.NewSession(&aws.Config{
      Region: aws.String(endpoints.UsWest2RegionID),
  }))

AWS リージョンとエンドポイントのメタデータについては、エンドポイントパッケージを参照してください。

セッションの作成時にリージョンを設定するだけでなく、 サービスごとのクライアントベースのリージョン。これは、 セッション。これは、特定のサービスクライアントを作成する場合に便利です。 セッションのリージョンとは異なるリージョン。

  svc := s3.New(sess, &aws.Config{
      Region: aws.String(endpoints.UsWest2RegionID),
  })

詳細と追加については、aws パッケージの Config タイプを参照してください。 エンドポイントの設定などのオプション、およびその他のサービス クライアント構成オプション。

API リクエストの作成

クライアントが作成されたら、サービスに対して API 要求を行うことができます。 各 API メソッドは入力パラメーターを受け取り、サービス応答を返します。 とエラー。SDK には、複数の方法で API 呼び出しを行うためのメソッドが用意されています。

このリストでは、さまざまな例として S3 ListObjects API を使用します。 APIリクエストを作成する方法。

  • リスト オブジェクト - サービスに対して API 要求を行う基本 API 操作。

  • ListObjectsRequest - Request の接尾辞が付いた API メソッドは、 API 要求ですが、送信しないでください。これは、 リクエストの署名付き URL を指定し、代わりに署名付き URL を共有します。 直接要求を行うアプリケーション。

  • ListObjectsPages - 基本 API オペレーションと同じですが、コールバックを使用して APIの応答のページネーションを自動的に処理します。

  • ListObjectsWithContext - 基本 API 操作と同じですが、 コンテキスト パターン。これは、のキャンセルを制御するのに役立ちます。 フライトリクエスト。詳細については、Go 標準ライブラリコンテキストパッケージを参照してください。 情報。このメソッドは、リクエストパッケージのオプション機能も取ります 要求の方法を変更するための可変個引数としてのオプション 作成された、または生のHTTP応答から情報を抽出します。

  • ListObjectsPagesWithContext - ListObjectsPages と同じですが、 コンテキスト パターン。ListObjectsWithContext と同様に、このメソッドも 要求パッケージの Option 関数オプション型を可変個引数として受け取ります。 引数。

API操作に加えて、SDKにはいくつかの上位レベルも含まれています AWS リソースが入るのを抽象的にチェックして待機するメソッド 望ましい状態。このリストでは、WaitUntilBucketExists を使用してデモンストレーションを行います。 ウェイターのさまざまな形。

  • 待機までバケットが存在する。- AWSのサービスを照会するためのAPIリクエストを行うメソッド リソースの状態。その状態が完了すると、正常に戻ります。

  • WaitUntilBucketExistsWithContext - WaitUntilBucketExists と同じですが、 コンテキストパターンのサポート。さらに、これらのメソッドは要求を受け取ります ウェイターを構成するためのパッケージのウェイターオプション、および基になる要求の方法 SDKによって作成されます。

API メソッドは、サービスが返す可能性のあるエラー コードを文書化します。 操作。これらのエラーは、プレフィックスとして const 文字列としても使用できます サービスクライアントのパッケージに "ErrCode" が含まれています。エラーがリストされていない場合 API の SDK ドキュメントでは、AWS サービスの API を参照する必要があります。 返される可能性のあるエラーのドキュメント。

  ctx := context.Background()

  result, err := svc.GetObjectWithContext(ctx, &s3.GetObjectInput{
      Bucket: aws.String("my-bucket"),
      Key: aws.String("my-key"),
  })
  if err != nil {
      // Cast err to awserr.Error to handle specific error codes.
      aerr, ok := err.(awserr.Error)
      if ok && aerr.Code() == s3.ErrCodeNoSuchKey {
          // Specific error code handling
      }
      return err
  }

  // Make sure to close the body when done with it for S3 GetObject APIs or
  // will leak connections.
  defer result.Body.Close()

  fmt.Println("Object Size:", aws.Int64Value(result.ContentLength))

API Request Pagination and Resource Waiters

Pagination helper methods are suffixed with "Pages", and provide the functionality needed to round trip API page requests. Pagination methods take a callback function that will be called for each page of the API's response.

   objects := []string{}
   err := svc.ListObjectsPagesWithContext(ctx, &s3.ListObjectsInput{
       Bucket: aws.String(myBucket),
   }, func(p *s3.ListObjectsOutput, lastPage bool) bool {
       for _, o := range p.Contents {
           objects = append(objects, aws.StringValue(o.Key))
       }
       return true // continue paging
   })
   if err != nil {
       panic(fmt.Sprintf("failed to list objects for bucket, %s, %v", myBucket, err))
   }

   fmt.Println("Objects in bucket:", objects)

Waiter helper methods provide the functionality to wait for an AWS resource state. These methods abstract the logic needed to check the state of an AWS resource, and wait until that resource is in a desired state. The waiter will block until the resource is in the state that is desired, an error occurs, or the waiter times out. If a resource times out the error code returned will be request.WaiterResourceNotReadyErrorCode.

  err := svc.WaitUntilBucketExistsWithContext(ctx, &s3.HeadBucketInput{
      Bucket: aws.String(myBucket),
  })
  if err != nil {
      aerr, ok := err.(awserr.Error)
      if ok && aerr.Code() == request.WaiterResourceNotReadyErrorCode {
          fmt.Fprintf(os.Stderr, "timed out while waiting for bucket to exist")
      }
      panic(fmt.Errorf("failed to wait for bucket to exist, %v", err))
  }
  fmt.Println("Bucket", myBucket, "exists")

Getting Help

Please use these community resources for getting help. We use the GitHub issues for tracking bugs and feature requests.

  • Ask a question on StackOverflow and tag it with the
    aws-sdk-go
    tag.
  • Come join the AWS SDK for Go community chat on gitter.
  • Open a support ticket with AWS Support.
  • If you think you may have found a bug, please open an issue.

This SDK implements AWS service APIs. For general issues regarding the AWS services and their limitations, you may also take a look at the Amazon Web Services Discussion Forums.

Opening Issues

If you encounter a bug with the AWS SDK for Go we would like to hear about it. Search the existing issues and see if others are also experiencing the issue before opening a new issue. Please include the version of AWS SDK for Go, Go language, and OS you’re using. Please also include reproduction case when appropriate.

The GitHub issues are intended for bug reports and feature requests. For help and questions with using AWS SDK for Go please make use of the resources listed in the Getting Help section. Keeping the list of open issues lean will help us respond in a timely manner.

Contributing

We work hard to provide a high-quality and useful SDK for our AWS services, and we greatly value feedback and contributions from our community. Please review our contributing guidelines before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.

SDK メジャーバージョンのメンテナンスとサポート

SDK メジャーバージョンのメンテナンスとサポート、および基盤となる依存関係については、AWS SDK とツールの共有設定と認証情報リファレンスガイドの以下を参照してください。

リソース

開発者ガイド - このドキュメント は、SDK を使用して構成および要求を行う方法に関する一般的な概要です。 SDK を初めて使用する場合は、このドキュメントと API ドキュメントは、作業を開始するのに役立ちます。このドキュメントでは、構文に焦点を当てています SDK の動作。サービス開発者ガイドは、特定の AWS のサービスの使用を開始するのに役立ちます。

SDK API リファレンス ドキュメント - 使用するもの AWSのすべてのAPIオペレーションの入力および出力パラメータを検索するためのドキュメント SDK でサポートされているサービス。API リファレンスには、次のドキュメントも含まれています。 SDK、およびSDKの使用方法の例、サービスクライアントAPI操作、および API 操作にはパラメーターが必要です。

サービスドキュメント - これを使用してください AWS のサービスとインターフェイスする方法を学ぶためのドキュメント。これらのガイドは次のとおりです。 サービスを開始する場合、または詳細を探している場合に最適 サービスに関する情報。このドキュメントはコーディングには必要ありませんが、 サービスは、注意すべき有用なサンプルを提供する場合があります。

SDK の例 - SDK のリポジトリには、SDK を使用したいくつかの手作りの例が含まれています。 機能と AWS のサービス。

フォーラム - 質問、ヘルプの取得、フィードバックの提供

問題 - 問題の報告、プル要求の送信、参加 (Apache 2.0 ライセンスを参照))