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

(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でチャットに参加します ビルドステータス ApacheV2ライセンス

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

SDKに追加された最新のバグ修正、更新、および機能については、リリースノートを確認してください

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

ジャンプ先:

入門

インストール

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

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

SDKを更新するには、SDK

go get -u
の最新バージョンを取得するために使用します。

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

依存関係

SDKには、

vendor
SDKの実行時の依存関係を含むフォルダーが含まれています。SDKの依存関係のメタデータは、Goモジュールファイル
go.mod
またはDepファイルにあります
Gopkg.toml

Goモジュール

Goモジュールを使用している場合は、

go get
デフォルトで最新のタグ付きリリースバージョンのSDKが使用されます。SDKの特定のリリースバージョンを取得するには、コマンドで使用
@<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に行く

ベンダーを有効にせずにGo1.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コアパッケージはすべて、SDKのルートにあるawsパッケージで利用できます。サポートされているAWSサービスの各クライアントは、SDKのルートにあるserviceフォルダーの下の独自のパッケージ内で利用できます。

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

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

    • クレデンシャル-SDKがAPIリクエストを行うためのAWSクレデンシャルを取得するために使用するタイプと組み込みのクレデンシャルプロバイダーを提供します。このフォルダーの下には、IAMロールを引き受けるためのstscredsやEC2インスタンスロール用のec2rolecredsなどの追加のクレデンシャルプロバイダーもネストされています。

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

    • セッション-初期のデフォルト構成を提供し、環境や共有クレデンシャルファイルなどの外部ソースから構成をロードします。

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

  • service-AWSサービスのクライアント。SDKでサポートされているすべてのサービスは、このフォルダーで利用できます。

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

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

AWSサービスのクライアントを作成するときは、最初にSession値を構築する必要があります。セッションは、サービスクライアント間で共有できる共有構成を提供します。サービスクライアントが作成されると、aws.Configタイプを介して追加の設定を渡し、セッションで提供される設定を上書きして、カスタム設定でサービスクライアントインスタンスを作成できます。

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

SDKの構成

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

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

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

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

クレデンシャルの構成

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

  • 環境クレデンシャル-特定の役割に対してサブプロセスを作成するときに役立つ環境変数のセット。

  • 共有クレデンシャルファイル(〜/ .aws / credentials)-このファイルは、プロファイル名に基づいてクレデンシャルを保存し、ローカル開発に役立ちます。

  • EC2インスタンスロールのクレデンシャル-EC2インスタンスロールを使用して、EC2インスタンスで実行されているアプリケーションにクレデンシャルを割り当てます。これにより、本番環境でクレデンシャルファイルを管理する必要がなくなります。

クレデンシャルは、Configのクレデンシャル値をカスタムプロバイダーに設定するか、SDKに含まれているプロバイダーの1つを使用してデフォルトのクレデンシャルチェーンをバイパスし、カスタムクレデンシャルを使用することで、コードで構成することもできます。これは、特定の資格情報またはプロバイダーのセットのみを使用するように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がAWSAPIリクエストを行うために使用するリージョンを指定する必要があります。SDKでは、環境変数を使用して領域を指定することも、セッションまたはサービスクライアントの作成時にコードで直接指定することもできます。リージョンが複数の方法で指定されている場合、コードで指定された最後の値が優先されます。

環境変数を使用してリージョンを設定するには、「AWS_REGION」をSDKで使用するリージョンに設定します。この方法を使用してリージョンを設定すると、リージョンを選択するためにアプリケーションに追加のコードを必要とせずに、複数のリージョンでアプリケーションを実行できます。

AWS_REGION=us-west-2

エンドポイントパッケージには、SDKが認識しているすべてのリージョンの定数が含まれています。値にはすべてRegionIDの接尾辞が付いています。これらの値は、リージョン文字列を手動で入力する必要性を減らすため、役立ちます。

セッションにリージョンを設定するには、awsパッケージのConfig structパラメーターRegionを、セッションから作成されたサービスクライアントが使用する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パッケージの設定タイプを参照してください。

APIリクエストの作成

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

このリストでは、APIリクエストを行うさまざまな方法の例としてS3ListObjectsAPIを使用します。

  • ListObjects-サービスへのAPIリクエストを行う基本API操作。

  • ListObjectsRequest-Requestの接尾辞が付いたAPIメソッドは、APIリクエストを作成しますが、送信しません。これは、リクエストの事前署名されたURLを取得し、アプリケーションが直接リクエストを行う代わりに事前署名されたURLを共有する場合にも役立ちます。

  • ListObjectsPages-基本API操作と同じですが、コールバックを使用してAPIの応答のページ付けを自動的に処理します。

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

  • ListObjectsPagesWithContext-ListObjectsPagesと同じですが、Contextパターンのサポートが追加されています。ListObjectsWithContextと同様に、このメソッドも可変引数としてリクエストパッケージのOption関数オプションタイプを取ります。

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

  • WaitUntilBucketExists。-AWSサービスにリソースの状態を照会するAPIリクエストを作成するメソッド。その状態が達成されると正常に戻ります。

  • WaitUntilBucketExistsWithContext-WaitUntilBucketExistsと同じですが、Contextパターンのサポートが追加されています。さらに、これらのメソッドは、リクエストパッケージのWaiterOptionsを使用してウェイターを構成し、SDKによって基になるリクエストがどのように行われるかを示します。

APIメソッドは、サービスが操作に対して返す可能性のあるエラーコードを文書化します。これらのエラーは、サービスクライアントのパッケージで「ErrCode」というプレフィックスが付いたconst文字列としても利用できます。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リクエストのページ付けとリソースウェイター

ページネーションヘルパーメソッドには「ページ」という接尾辞が付いており、APIページリクエストをラウンドトリップするために必要な機能を提供します。ページネーションメソッドは、APIの応答の各ページに対して呼び出されるコールバック関数を取ります。

   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)

ウェイターヘルパーメソッドは、AWSリソースの状態を待機する機能を提供します。これらのメソッドは、AWSリソースの状態をチェックするために必要なロジックを抽象化し、そのリソースが目的の状態になるまで待機します。ウェイターは、リソースが目的の状態になるか、エラーが発生するか、ウェイターがタイムアウトするまでブロックします。リソースがタイムアウトした場合、返されるエラーコードは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")

ヘルプを取得する

ヘルプを得るには、これらのコミュニティリソースを使用してください。バグや機能リクエストを追跡するためにGitHubの問題を使用します。

このSDKはAWSサービスAPIを実装しています。AWSサービスとその制限に関する一般的な問題については、アマゾンウェブサービスディスカッションフォーラムもご覧ください。

冒頭の問題

AWS SDK for Goでバグが発生した場合は、それについてお聞きしたいと思います。新しい問題を開く前に、既存の問題を検索し、他の人も問題を経験しているかどうかを確認してください。使用しているAWSSDKfor Go、Go言語、およびOSのバージョンを含めてください。必要に応じて、複製ケースも含めてください。

GitHubの問題は、バグレポートと機能リクエストを対象としています。AWS SDK for Goの使用に関するヘルプと質問については、「ヘルプの取得」セクションにリストされているリソースを利用してください。未解決の問題のリストを無駄のない状態に保つことは、タイムリーに対応するのに役立ちます。

貢献

AWSサービスに高品質で便利なSDKを提供するために懸命に取り組んでおり、コミュニティからのフィードバックと貢献を大いに評価しています。問題プルリクエストを送信する前に、投稿ガイドラインを確認して、バグレポートや投稿に効果的に対応するために必要なすべての情報があることを確認してください。

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

SDKメジャーバージョンとその基礎となる依存関係のメンテナンスとサポートについては、AWS SDK and Tools Shared ConfigurationandCredentialsリファレンスガイドの以下を参照してください。

資力

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

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

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

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

フォーラム-質問をしたり、助けを求めたり、フィードバックを提供したりする

問題-問題を報告し、プルリクエストを送信し、参加します(Apache 2.0ライセンスを参照) 。