最小 Go バージョンモジュール化設定のロードモッキングと *iface 認証情報と認証情報プロバイダーサービスクライアントリクエストのカスタマイズ機能サービスカスタマイズの変更

v2 AWS SDK for Go への移行

最小 Go バージョン

には、最低 Go バージョン 1.20 AWS SDK for Go が必要です。Go の最新バージョンは、ダウンロードページでダウンロードできます。各 Go バージョンリリースの詳細と、アップグレードに必要な関連情報については、リリース履歴を参照してください。

モジュール化

AWS SDK for Go は、Go 1.13 のデフォルト開発モードになった Go モジュールを利用するように更新されました。SDK が提供する多くのパッケージはモジュール化されており、それぞれ独立してバージョン管理およびリリースされています。この変更により、アプリケーションの依存関係モデリングが改善され、SDK は Go モジュールのバージョニング戦略に従う新機能を提供できるようになります。

次のリストは、 SDK が提供するいくつかの Go モジュールです。

モジュール	説明
`github.com/aws/aws-sdk-go-v2`	SDK コア
`github.com/aws/aws-sdk-go-v2/config`	共有設定のロード
`github.com/aws/aws-sdk-go-v2/credentials`	AWS 認証情報プロバイダー
`github.com/aws/aws-sdk-go-v2/feature/ec2/imds`	Amazon EC2 インスタンスメタデータサービスクライアント

SDK のサービスクライアントと上位レベルのユーティリティモジュールは、次のインポートパスの下にネストされます。

ルートをインポートする	説明
`github.com/aws/aws-sdk-go-v2/service/`	サービスクライアントモジュール
`github.com/aws/aws-sdk-go-v2/feature/`	Amazon S3 Transfer Manager などのサービスの高レベルユーティリティ

設定のロード

セッションパッケージと関連する機能は、設定パッケージによって提供される簡略化された設定システムに置き換えられます。config パッケージは別の Go モジュールであり、を使用してアプリケーションの依存関係に含めることができますgo get。


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

session.New、session.NewSession、NewSessionWithOptions、および session.Must は config.LoadDefaultConfig に移行する必要があります。

config パッケージには、共有設定のロードをプログラムで上書きするのに役立ついくつかのヘルパー関数が用意されています。これらの関数名にはプレフィックスが付き、その後に上書きするオプションがWith続きます。session パッケージの使用を移行する方法の例をいくつか見てみましょう。

共有設定のロードの詳細については、「」を参照してくださいSDK を設定。

例

NewSession から LoadDefaultConfig への移行

次の例は、引数パラメータを追加session.NewSessionせずにの使用をに移行する方法を示していますconfig.LoadDefaultConfig。


// V1 using NewSession

import "github.com/aws/aws-sdk-go/aws/session"

// ...

sess, err := session.NewSession()
if err != nil {
    // handle error
}


// V2 using LoadDefaultConfig

import "context"
import "github.com/aws/aws-sdk-go-v2/config"

// ...

cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
    // handle error
}

aws.Config オプションを使用した NewSession からの移行

この例では、設定のロード中にaws.Config値の上書きを移行する方法を示しています。1 つ以上のconfig.With*ヘルパー関数をに提供config.LoadDefaultConfigして、ロードされた設定値を上書きできます。この例では、 AWS リージョンは config.WithRegion ヘルパー関数us-west-2を使用してに上書きされます。


// V1

import "github.com/aws/aws-sdk-go/aws"
import "github.com/aws/aws-sdk-go/aws/session"

// ...

sess, err := session.NewSession(aws.Config{
    Region: aws.String("us-west-2")
})
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/config"

// ...

cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithRegion("us-west-2"),
)
if err != nil {
    // handle error
}

NewSessionWithOptions からの移行

この例では、設定のロード中にオーバーライド値を移行する方法を示します。ゼロ以上のconfig.With*ヘルパー関数をに提供config.LoadDefaultConfigして、ロードされた設定値を上書きできます。この例では、 AWS SDK 共有設定をロードするときに使用するターゲットプロファイルを上書きする方法を示します。


// V1

import "github.com/aws/aws-sdk-go/aws"
import "github.com/aws/aws-sdk-go/aws/session"

// ...

sess, err := session.NewSessionWithOptions(aws.Config{
    Profile: "my-application-profile"
})
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/config"

// ...

cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithSharedConfigProfile("my-application-profile"),
)
if err != nil {
    // handle error
}

モッキングと `*iface`

パッケージ*ifaceとインターフェイス (s3iface.S3API など) が削除されました。これらのインターフェイス定義は、サービスが新しいオペレーションを追加するたびに壊れるため、安定していません。

の使用は、使用するサービスオペレーションのスコープ付き発信者定義インターフェイスに置き換え*ifaceる必要があります。


// V1

import "io"

import "github.com/aws/aws-sdk-go/service/s3"
import "github.com/aws/aws-sdk-go/service/s3/s3iface"

func GetObjectBytes(client s3iface.S3API, bucket, key string) ([]byte, error) {
    object, err := client.GetObject(&s3.GetObjectInput{
        Bucket: &bucket,
        Key:    &key,
    })
    if err != nil {
        return nil, err
    }
    defer object.Body.Close()

    return io.ReadAll(object.Body)
}


// V2

import "context"
import "io"

import "github.com/aws/aws-sdk-go-v2/service/s3"

type GetObjectAPIClient interface {
    GetObject(context.Context, *s3.GetObjectInput, ...func(*s3.Options)) (*s3.GetObjectOutput, error)
}

func GetObjectBytes(ctx context.Context, client GetObjectAPIClient, bucket, key string) ([]byte, error) {
    object, err := client.GetObject(ctx, &s3.GetObjectInput{
        Bucket: &bucket,
        Key:    &key,
    })
    if err != nil {
        return nil, err
    }
    defer object.Body.Close()

    return io.ReadAll(object.Body)
}

詳細については、「v2 AWS SDK for Go を使用したユニットテスト」を参照してください。

認証情報と認証情報プロバイダー

aws/credentials パッケージと関連する認証情報プロバイダーが認証情報パッケージの場所に移動されました。credentials パッケージは、を使用して取得する Go モジュールですgo get。


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

AWS SDK for Go v2 リリースでは AWS 、認証情報プロバイダーが更新され、認証情報を取得 AWS するための一貫したインターフェイスが提供されます。各プロバイダーは aws.CredentialsProvider インターフェイスを実装します。これは、v1 credentials.Value タイプに類似した (aws.Credentials, error). aws.Credentials AWS SDK for Go を返すRetrieveメソッドを定義します。

認証情報キャッシュを実行するには、aws.CredentialsCache でaws.CredentialsProviderオブジェクトをラップする必要があります。NewCredentialsCache を使用してaws.CredentialsCacheオブジェクトを作成します。デフォルトでは、によって設定された認証情報config.LoadDefaultConfigはでラップされますaws.CredentialsCache。

次の表は、認証情報プロバイダーの場所を AWS AWS SDK for Go v1 から v2 に変更したものです。

名前	V1 インポート	V2 インポート
Amazon EC2 IAM ロールの認証情報	`github.com/aws/aws-sdk-go/aws/credentials/ec2rolecreds`	`github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds`
エンドポイント認証情報	`github.com/aws/aws-sdk-go/aws/credentials/endpointcreds`	`github.com/aws/aws-sdk-go-v2/credentials/endpointcreds`
認証情報の処理	`github.com/aws/aws-sdk-go/aws/credentials/processcreds`	`github.com/aws/aws-sdk-go-v2/credentials/processcreds`
AWS Security Token Service	`github.com/aws/aws-sdk-go/aws/credentials/stscreds`	`github.com/aws/aws-sdk-go-v2/credentials/stscreds`

静的な認証情報

credentials.NewStaticCredentials を使用して静的認証情報をプログラムで構築するアプリケーションは、Credentials.NewStaticCredentialsProvider を使用する必要があります。

例


// V1

import "github.com/aws/aws-sdk-go/aws/credentials"

// ...

appCreds := credentials.NewStaticCredentials(accessKey, secretKey, sessionToken)
value, err := appCreds.Get()
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/aws"
import "github.com/aws/aws-sdk-go-v2/credentials"

// ...

appCreds := aws.NewCredentialsCache(credentials.NewStaticCredentialsProvider(accessKey, secretKey, sessionToken))
value, err := appCreds.Retrieve(context.TODO())
if err != nil {
    // handle error
}

Amazon EC2 IAM ロールの認証情報

NewCredentials を使用するには、NewCredentials と NewCredentialsWithClient https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds#Newの使用を移行する必要があります。

ec2rolecreds パッケージの ec2rolecreds.Newは、ec2rolecreds.Options の機能オプションを入力として受け取り、使用する特定の Amazon EC2 インスタンスメタデータサービスクライアントを上書きしたり、認証情報の有効期限を上書きしたりできます。

例


// V1

import "github.com/aws/aws-sdk-go/aws/credentials/ec2rolecreds"

// ...

appCreds := ec2rolecreds.NewCredentials(sess)
value, err := appCreds.Get()
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/aws"
import "github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds"

// ...

// New returns an object of a type that satisfies the aws.CredentialProvider interface
appCreds := aws.NewCredentialsCache(ec2rolecreds.New())
value, err := appCreds.Retrieve(context.TODO())
if err != nil {
    // handle error
}

エンドポイント認証情報

New を使用するには、NewCredentialsClient と NewProviderClient https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/endpointcreds#Newの使用を移行する必要があります。

endpointcreds パッケージの New関数は、認証情報を取得する HTTP または HTTPS エンドポイントの URL、および endpointcreds.Options の機能オプションを含む文字列引数を取り、認証情報プロバイダーを変更して特定の設定を上書きします。

認証情報の処理

NewProvider または NewProvider を使用するには、NewCredentials、NewCredentialsCommand、および NewCredentialsTimeout NewProviderCommandの使用を移行する必要があります。 NewCredentialsCommand

processcreds パッケージの NewProvider関数は、ホスト環境のシェルで実行されるコマンドである文字列引数と、オプションの機能オプションを使用して認証情報プロバイダーをミューテーションし、特定の設定を上書きします。

NewProviderCommand は、1 つ以上のコマンドライン引数を取る、または特定の実行環境要件を持つ、より複雑なプロセスコマンドを定義する NewCommandBuilder インターフェイスを実装します。DefaultNewCommandBuilder はこのインターフェイスを実装し、複数のコマンドライン引数を必要とするプロセスのコマンドビルダーを定義します。

例


// V1

import "github.com/aws/aws-sdk-go/aws/credentials/processcreds"

// ...

appCreds := processcreds.NewCredentials("/path/to/command")
value, err := appCreds.Get()
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/aws"
import "github.com/aws/aws-sdk-go-v2/credentials/processcreds"

// ...

appCreds := aws.NewCredentialsCache(processcreds.NewProvider("/path/to/command"))
value, err := appCreds.Retrieve(context.TODO())
if err != nil {
    // handle error
}

AWS Security Token Service 認証情報

AssumeRole

NewAssumeRoleProvider を使用するには、NewCredentials と NewCredentialsWithClient の使用を移行する必要があります。

stscreds パッケージの NewAssumeRoleProvider関数は、sts.Client、および指定されたの設定済み認証情報から引き受ける AWS Identity and Access Management ロール ARN を使用して呼びsts.Client出す必要があります。AssumeRoleOptions の機能オプションのセットを指定して、プロバイダーの他のオプション設定を変更することもできます。

例


// V1

import "github.com/aws/aws-sdk-go/aws/credentials/stscreds"

// ...

appCreds := stscreds.NewCredentials(sess, "arn:aws:iam::123456789012:role/demo")
value, err := appCreds.Get()
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/credentials/stscreds"
import "github.com/aws/aws-sdk-go-v2/service/sts"

// ...

client := sts.NewFromConfig(cfg)

appCreds := stscreds.NewAssumeRoleProvider(client, "arn:aws:iam::123456789012:role/demo")
value, err := appCreds.Retrieve(context.TODO())
if err != nil {
    // handle error
}

AssumeRoleWithWebIdentity

NewWebIdentityCredentials NewWebIdentityRoleProvider、および NewWebIdentityRoleProviderWithToken の使用を移行する必要があります。 NewWebIdentityRoleProvider

stscreds パッケージの NewWebIdentityRoleProvider関数は、sts.Client、指定された sts.Clientの設定済み認証情報を使用して引き受ける AWS Identity and Access Management ロール ARN、および OAuth 2.0 または OpenID Connect ID トークンを提供するための IdentityTokenRetriever の実装を使用して呼び出される必要があります。IdentityTokenFile IdentityTokenRetriever は、アプリケーションのホストファイルシステムにあるファイルからウェブ ID トークンを提供するために使用できるです。WebIdentityRoleOptions の機能オプションのセットを指定して、プロバイダーの他のオプション設定を変更することもできます。

例


// V1

import "github.com/aws/aws-sdk-go/aws/credentials/stscreds"

// ...

appCreds := stscreds.NewWebIdentityRoleProvider(sess, "arn:aws:iam::123456789012:role/demo", "sessionName", "/path/to/token")
value, err := appCreds.Get()
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/aws"
import "github.com/aws/aws-sdk-go-v2/credentials/stscreds"
import "github.com/aws/aws-sdk-go-v2/service/sts"

// ...

client := sts.NewFromConfig(cfg)

appCreds := aws.NewCredentialsCache(stscreds.NewWebIdentityRoleProvider(
        client,
        "arn:aws:iam::123456789012:role/demo",
        stscreds.IdentityTokenFile("/path/to/file"),
        func(o *stscreds.WebIdentityRoleOptions) {
            o.RoleSessionName = "sessionName"
        }))
value, err := appCreds.Retrieve(context.TODO())
if err != nil {
    // handle error
}

サービスクライアント

AWS SDK for Go は、github.com/aws/aws-sdk-go-v2/serviceインポートパスの下にネストされたサービスクライアントモジュールを提供します。各サービスクライアントは、各サービスの一意の識別子を使用して Go パッケージに含まれています。次の表に、のサービスインポートパスの例をいくつか示します AWS SDK for Go。

サービス名	V1 インポートパス	V2 インポートパス
Amazon S3	`github.com/aws/aws-sdk-go/service/s3`	`github.com/aws/aws-sdk-go-v2/service/s3`
Amazon DynamoDB	`github.com/aws/aws-sdk-go/service/dynamodb`	`github.com/aws/aws-sdk-go-v2/service/dynamodb`
Amazon CloudWatch Logs	`github.com/aws/aws-sdk-go/service/cloudwatchlogs`	`github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs`

各サービスクライアントパッケージは、個別にバージョニングされた Go モジュールです。アプリケーションの依存関係としてサービスクライアントを追加するには、サービスのインポートパスで go get コマンドを使用します。例えば、Amazon S3 クライアントを依存関係に追加するには、を使用します。


go get github.com/aws/aws-sdk-go-v2/service/s3

クライアントの構築

クライアントのパッケージの NewまたはコンNewFromConfigストラクタ関数 AWS SDK for Go を使用して、でクライアントを構築できます。 AWS SDK for Go v1 から移行する場合は、 NewFromConfigバリアントを使用することをお勧めします。これにより、の値を使用して新しいサービスクライアントが返されますaws.Config。このaws.Config値は、を使用して SDK 共有設定をロードするときに作成されますconfig.LoadDefaultConfig。サービスクライアントの作成の詳細については、「」を参照してくださいAWS サービスで AWS SDK for Go v2 を使用する。

例 1


// V1

import "github.com/aws/aws-sdk-go/aws/session"
import "github.com/aws/aws-sdk-go/service/s3"

// ...

sess, err := session.NewSession()
if err != nil {
    // handle error
}

client := s3.New(sess)


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"

// ...

cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
    // handle error
}

client := s3.NewFromConfig(cfg)

例 2: クライアント設定の上書き


// V1

import "github.com/aws/aws-sdk-go/aws"
import "github.com/aws/aws-sdk-go/aws/session"
import "github.com/aws/aws-sdk-go/service/s3"

// ...

sess, err := session.NewSession()
if err != nil {
    // handle error
}

client := s3.New(sess, &aws.Config{
    Region: aws.String("us-west-2"),
})


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"

// ...

cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
    // handle error
}

client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.Region = "us-west-2"
})

エンドポイント

エンドポイントパッケージがに存在しなくなりました AWS SDK for Go。各サービスクライアントは、クライアントパッケージに必要な AWS エンドポイントメタデータを埋め込むようになりました。これにより、アプリケーションで使用されていないサービスのエンドポイントメタデータが含まれなくなるため、コンパイルされたアプリケーションの全体的なバイナリサイズが削減されます。

さらに、各サービスがでエンドポイント解決用の独自のインターフェイスを公開するようになりましたEndpointResolverV2。各 API は、サービスの一意のパラメータセットを取得しEndpointParameters、その値は、オペレーションが呼び出されたときに SDK によってさまざまな場所から取得されます。

デフォルトでは、サービスクライアントは設定された AWS リージョンを使用して、ターゲットリージョンのサービスエンドポイントを解決します。アプリケーションでカスタムエンドポイントが必要な場合は、 aws.Config 構造の EndpointResolverV2フィールドでカスタム動作を指定できます。アプリケーションがカスタムエンドポイントを実装している場合。リゾルバーは、この新しいサービスごとのインターフェイスに準拠するように移行する必要があります。

エンドポイントとカスタムリゾルバーの実装の詳細については、「」を参照してくださいクライアントエンドポイントの設定。

認証

AWS SDK for Go は、より高度な認証動作をサポートしているため、codecatalyst や S3 Express One Zone などの新しい AWS サービス機能を使用できます。さらに、この動作はクライアントごとにカスタマイズできます。

API オペレーションの呼び出し

サービスクライアントのオペレーション方法の数が大幅に減少しました。<OperationName>Request、<OperationName>WithContext、および <OperationName>メソッドはすべて 1 つのオペレーションメソッドに統合されています<OperationName>。

例

次の例は、Amazon S3 PutObject オペレーションへの呼び出しを AWS SDK for Go v1 から v2 に移行する方法を示しています。


// V1

import "context"
import "github.com/aws/aws-sdk-go/service/s3"

// ...

client := s3.New(sess)

// Pattern 1
output, err := client.PutObject(&s3.PutObjectInput{
    // input parameters
})

// Pattern 2
output, err := client.PutObjectWithContext(context.TODO(), &s3.PutObjectInput{
    // input parameters
})

// Pattern 3
req, output := client.PutObjectRequest(context.TODO(), &s3.PutObjectInput{
    // input parameters
})
err := req.Send()


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/service/s3"

// ...

client := s3.NewFromConfig(cfg)

output, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
    // input parameters
})

サービスデータ型

オペレーションの最上位入出力タイプは、サービスクライアントパッケージにあります。特定のオペレーションの入出力タイプは <OperationName>Inputおよびのパターンに従います。ここで<OperationName>Output、 OperationName は呼び出すオペレーションの名前です。例えば、Amazon S3 PutObject オペレーションの入出力シェイプは、それぞれ PutObjectInput と PutObjectOutput です。

入力タイプと出力タイプを除く他のすべてのサービスデータ型は、サービスクライアントtypesパッケージのインポートパス階層にあるパッケージに移行されています。たとえば、s3.AccessControlPolicy タイプが types.AccessControlPolicy に配置されるようになりました。

列挙値

SDK は、すべての API 列挙フィールドに対して型付きエクスペリエンスを提供するようになりました。サービス API リファレンスドキュメントからコピーされた文字列リテラル値を使用する代わりに、サービスクライアントの typesパッケージにある具体的なタイプのいずれかを使用できるようになりました。たとえば、オブジェクトに適用する ACL を Amazon S3 PutObjectInput オペレーションに提供できます。 AWS SDK for Go v1 では、このパラメータは *string型でした。では AWS SDK for Go、このパラメータは types.ObjectCannedACL になりました。types パッケージは、このフィールドに割り当てることができる有効な列挙値に対して生成された定数を提供します。例えば、types.ObjectCannedACLPrivate は「private」の既定 ACL 値の定数です。この値は、アプリケーション内の文字列定数を管理する代わりに使用できます。

ポインタパラメータ

AWS SDK for Go v1 では、すべての入力パラメータに対してサービスオペレーションに渡されるポインタリファレンスが必要でした。 AWS SDK for Go v2 では、入力値をポインタとして渡す必要がなくなるため、ほとんどのサービスのエクスペリエンスが簡素化されました。この変更により、多くのサービスクライアントオペレーションで、アプリケーションが uint8、、uint16、、uint32、、int8int16、int32float32float64、タイプのポインタ参照を渡す必要がなくなりましたbool。同様に、スライス要素タイプとマップ要素タイプは、要素をポインタ参照として渡す必要があるかどうかを反映するように更新されました。

aws パッケージには、Go 組み込みタイプのポインタを作成するためのヘルパー関数が含まれています。これらのヘルパーを使用して、これらの Go タイプのポインタタイプの作成をより簡単に処理する必要があります。同様に、ヘルパーメソッドは、これらのタイプのポインタ値を安全に参照解除するために提供されます。たとえば、aws.String 関数は ⇒ string から変換します*string。逆に、aws.ToString は *string ⇒ から変換されますstring。アプリケーションを AWS SDK for Go v1 から v2 にアップグレードするときは、ポインタタイプから非ポインタバリアントに変換するためのヘルパーの使用を移行する必要があります。たとえば、aws.StringValue はに更新する必要がありますaws.ToString。

エラータイプ

AWS SDK for Go は、Go 1.13 で導入されたエラーラッピング機能を最大限に活用します。エラーレスポンスをモデル化するサービスは、クライアントのtypesパッケージで使用可能なタイプを生成し、クライアントオペレーションエラーがこれらのタイプの 1 つによって引き起こされたかどうかをテストするために使用できます。例えば、Amazon S3 GetObjectオペレーションは、存在しないオブジェクトキーを取得しようとするとNoSuchKeyエラーを返す可能性があります。errors.As を使用して、返されたオペレーションエラーがタイプであるかどうかをテストできます。NoSuchKey エラー。サービスが特定のタイプのエラーをモデル化しない場合は、smithy.APIError インターフェイスタイプを使用して、サービスから返されたエラーコードとメッセージを検査できます。この機能は、awserr.Error および v1 の他の awserr AWS SDK for Go 機能を置き換えます。エラーの処理の詳細については、「」を参照してくださいAWS SDK for Go V2 でのエラーの処理。

例


// V1

import "github.com/aws/aws-sdk-go/aws/awserr"
import "github.com/aws/aws-sdk-go/service/s3"

// ...

client := s3.New(sess)

output, err := s3.GetObject(&s3.GetObjectInput{
    // input parameters
})
if err != nil {
    if awsErr, ok := err.(awserr.Error); ok {
        if awsErr.Code() == "NoSuchKey" {
            // handle NoSuchKey
        } else {
            // handle other codes
        }
        return
    }
    // handle a error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/service/s3"
import "github.com/aws/aws-sdk-go-v2/service/s3/types"
import "github.com/aws/smithy-go"

// ...

client := s3.NewFromConfig(cfg)

output, err := client.GetObject(context.TODO(), &s3.GetObjectInput{
    // input parameters
})
if err != nil {
    var nsk *types.NoSuchKey
    if errors.As(err, &nsk) {
        // handle NoSuchKey error
        return
    }
    var apiErr smithy.APIError
    if errors.As(err, &apiErr) {
        code := apiErr.ErrorCode()
        message := apiErr.ErrorMessage()
        // handle error code
        return
    }
    // handle error
    return
}

ページネーター

サービスオペレーションページネーターは、サービスクライアントのメソッドとして呼び出されなくなりました。オペレーションにページネーターを使用するには、いずれかのページネーターコンストラクタメソッドを使用してオペレーションのページネーターを構築する必要があります。例えば、Amazon S3 ListObjectsV2オペレーションでページ分割を使用するには、s3.NewListObjectsV2Paginator を使用してページネーターを構築する必要があります。このコンストラクタは、メソッドを提供する ListObjectsV2Paginator を返しHasMorePages、取得するページがあるかどうかNextPageを判断し、それぞれ次のページを取得するオペレーションを呼び出します。SDK ページネーターの使用の詳細については、「」を参照してくださいオペレーションページネーターの使用。

v1 ページネーターから AWS SDK for Go v2 AWS SDK for Go 同等のページネーターに移行する方法の例を見てみましょう。

例


// V1

import "fmt"
import "github.com/aws/aws-sdk-go/service/s3"

// ...

client := s3.New(sess)

params := &s3.ListObjectsV2Input{
    // input parameters
}

totalObjects := 0
err := client.ListObjectsV2Pages(params, func(output *s3.ListObjectsV2Output, lastPage bool) bool {
    totalObjects += len(output.Contents)
    return !lastPage
})
if err != nil {
    // handle error
}
fmt.Println("total objects:", totalObjects)


// V2

import "context"
import "fmt"
import "github.com/aws/aws-sdk-go-v2/service/s3"

// ...

client := s3.NewFromConfig(cfg)

params := &s3.ListObjectsV2Input{
    // input parameters
}

totalObjects := 0
paginator := s3.NewListObjectsV2Paginator(client, params)
for paginator.HasMorePages() {
    output, err := paginator.NextPage(context.TODO())
    if err != nil {
        // handle error
    }
    totalObjects += len(output.Contents)
}
fmt.Println("total objects:", totalObjects)

ウェイター

サービスオペレーションウェーターは、サービスクライアントのメソッドとして呼び出されなくなりました。ウェーターを使用するには、まず目的のウェータータイプを構築し、次に待機メソッドを呼び出します。例えば、Amazon S3 バケットが存在するのを待つには、BucketExistsウェーターを構築する必要があります。s3.NewBucketExistsWaiter コンストラクタを使用して s3.BucketExistsWaiter を作成します。s3.BucketExistsWaiter には、バケットが利用可能になるまで待機するために使用できるWaitメソッドが用意されています。

署名付きリクエスト

V1 SDK は技術的に SDK オペレーションの AWS 事前署名をサポートしていましたが、これはサービスレベルで実際にサポートされている内容を正確に表していません (実際には、ほとんどの AWS サービスオペレーションは事前署名をサポートしていません）。

AWS SDK for Go は、サポートされている事前署名可能なオペレーションの特定の APIs を使用してサービスパッケージ内の特定のPresignClient実装を公開することで、これを解決します。

注: SDK v1 で正常に使用していたオペレーションの事前署名サポートがサービスにない場合は、GitHub に問題を提出してお知らせください。

Presign と PresignRequest の使用は、サービス固有の事前署名クライアントを使用するように変換する必要があります。

次の例は、S3 GetObject リクエストの事前署名を移行する方法を示しています。


// V1

import (
    "fmt"
    "time"

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

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

    svc := s3.New(sess)
    req, _ := svc.GetObjectRequest(&s3.GetObjectInput{
        Bucket: aws.String("amzn-s3-demo-bucket"),
        Key:    aws.String("key"),
    })

    // pattern 1
    url1, err := req.Presign(20 * time.Minute)
    if err != nil {
        panic(err)
    }
    fmt.Println(url1)

    // pattern 2
    url2, header, err := req.PresignRequest(20 * time.Minute)
    if err != nil {
        panic(err)
    }
    fmt.Println(url2, header)
}


// V2

import (
    "context"
    "fmt"
    "time"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
    cfg, err := config.LoadDefaultConfig(context.Background())
    if err != nil {
        panic(err)
    }

    svc := s3.NewPresignClient(s3.NewFromConfig(cfg))
    req, err := svc.PresignGetObject(context.Background(), &s3.GetObjectInput{
        Bucket: aws.String("amzn-s3-demo-bucket"),
        Key:    aws.String("key"),
    }, func(o *s3.PresignOptions) {
        o.Expires = 20 * time.Minute
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(req.Method, req.URL, req.SignedHeader)
}

リクエストのカスタマイズ

モノリシック request.Request API が再分割されました。

オペレーション入出力

オペレーションの入出力構造をそれぞれ保持Dataする不透明なRequestフィールド Params とは、特定のミドルウェアフェーズ内で入出力としてアクセスできるようになりました。

およびを参照Request.Paramsし、ミドルウェアに移行Request.Dataする必要があるリクエストハンドラー。

移行 `Params`


// V1

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

func withPutObjectDefaultACL(acl string) request.Option {
    return func(r *request.Request) {
        in, ok := r.Params.(*s3.PutObjectInput)
        if !ok {
            return
        }

        if in.ACL == nil {
            in.ACL = aws.String(acl)
        }
        r.Params = in
    }
}

func main() {
    sess := session.Must(session.NewSession())
    sess.Handlers.Validate.PushBack(withPutObjectDefaultACL(s3.ObjectCannedACLBucketOwnerFullControl))

    // ...
}


// V2

import (
    "context"

    "github.com/aws/aws-sdk-go-v2/service/s3"
    "github.com/aws/aws-sdk-go-v2/service/s3/types"
    "github.com/aws/smithy-go/middleware"
    smithyhttp "github.com/aws/smithy-go/transport/http"
)

type withPutObjectDefaultACL struct {
    acl types.ObjectCannedACL
}

// implements middleware.InitializeMiddleware, which runs BEFORE a request has
// been serialized and can act on the operation input
var _ middleware.InitializeMiddleware = (*withPutObjectDefaultACL)(nil)

func (*withPutObjectDefaultACL) ID() string {
    return "withPutObjectDefaultACL"
}

func (m *withPutObjectDefaultACL) HandleInitialize(ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler) (
    out middleware.InitializeOutput, metadata middleware.Metadata, err error,
) {
    input, ok := in.Parameters.(*s3.PutObjectInput)
    if !ok {
        return next.HandleInitialize(ctx, in)
    }

    if len(input.ACL) == 0 {
        input.ACL = m.acl
    }
    in.Parameters = input
    return next.HandleInitialize(ctx, in)
}

// create a helper function to simplify instrumentation of our middleware
func WithPutObjectDefaultACL(acl types.ObjectCannedACL) func (*s3.Options) {
    return func(o *s3.Options) {
        o.APIOptions = append(o.APIOptions, func (s *middleware.Stack) error {
            return s.Initialize.Add(&withPutObjectDefaultACL{acl: acl}, middleware.After)
        })
    }
}

func main() {
    cfg, err := config.LoadDefaultConfig(context.Background())
    if err != nil {
        // ...
    }

    svc := s3.NewFromConfig(cfg, WithPutObjectDefaultACL(types.ObjectCannedACLBucketOwnerFullControl))
    // ...
}

移行 `Data`


// V1

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

func readPutObjectOutput(r *request.Request) {
        output, ok := r.Data.(*s3.PutObjectOutput)
        if !ok {
            return
        }

        // ...
    }
}

func main() {
    sess := session.Must(session.NewSession())
    sess.Handlers.Unmarshal.PushBack(readPutObjectOutput)

    svc := s3.New(sess)
    // ...
}


// V2

import (
    "context"

    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
    "github.com/aws/smithy-go/middleware"
    smithyhttp "github.com/aws/smithy-go/transport/http"
)

type readPutObjectOutput struct{}

var _ middleware.DeserializeMiddleware = (*readPutObjectOutput)(nil)

func (*readPutObjectOutput) ID() string {
    return "readPutObjectOutput"
}

func (*readPutObjectOutput) HandleDeserialize(ctx context.Context, in middleware.DeserializeInput, next middleware.DeserializeHandler) (
    out middleware.DeserializeOutput, metadata middleware.Metadata, err error,
) {
    out, metadata, err = next.HandleDeserialize(ctx, in)
    if err != nil {
        // ...
    }

    output, ok := in.Parameters.(*s3.PutObjectOutput)
    if !ok {
        return out, metadata, err
    }

    // inspect output...

    return out, metadata, err
}

func WithReadPutObjectOutput(o *s3.Options) {
    o.APIOptions = append(o.APIOptions, func (s *middleware.Stack) error {
        return s.Initialize.Add(&withReadPutObjectOutput{}, middleware.Before)
    })
}

func main() {
    cfg, err := config.LoadDefaultConfig(context.Background())
    if err != nil {
        // ...
    }

    svc := s3.NewFromConfig(cfg, WithReadPutObjectOutput)
    // ...
}

HTTP リクエスト/レスポンス

のフィールドHTTPRequestと HTTPResponseフィールドRequestが、特定のミドルウェアフェーズで公開されるようになりました。ミドルウェアはトランスポートに依存しないため、ミドルウェアの入力または出力に対して型アサーションを実行して、基盤となる HTTP リクエストまたはレスポンスを明らかにする必要があります。

ミドルウェアに移行Request.HTTPResponseする必要がある Request.HTTPRequestとを参照するリクエストハンドラー。

移行 `HTTPRequest`


// V1

import (
    "github.com/aws/aws-sdk-go/aws/request"
    "github.com/aws/aws-sdk-go/aws/session"
)

func withHeader(header, val string) request.Option {
    return func(r *request.Request) {
        request.HTTPRequest.Header.Set(header, val)
    }
}

func main() {
    sess := session.Must(session.NewSession())
    sess.Handlers.Build.PushBack(withHeader("x-user-header", "..."))

    svc := s3.New(sess)
    // ...
}


// V2

import (
    "context"
    "fmt"

    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
    "github.com/aws/smithy-go/middleware"
    smithyhttp "github.com/aws/smithy-go/transport/http"
)

type withHeader struct {
    header, val string
}

// implements middleware.BuildMiddleware, which runs AFTER a request has been
// serialized and can operate on the transport request
var _ middleware.BuildMiddleware = (*withHeader)(nil)

func (*withHeader) ID() string {
    return "withHeader"
}

func (m *withHeader) HandleBuild(ctx context.Context, in middleware.BuildInput, next middleware.BuildHandler) (
    out middleware.BuildOutput, metadata middleware.Metadata, err error,
) {
    req, ok := in.Request.(*smithyhttp.Request)
    if !ok {
        return out, metadata, fmt.Errorf("unrecognized transport type %T", in.Request)
    }

    req.Header.Set(m.header, m.val)
    return next.HandleBuild(ctx, in)
}

func WithHeader(header, val string) func (*s3.Options) {
    return func(o *s3.Options) {
        o.APIOptions = append(o.APIOptions, func (s *middleware.Stack) error {
            return s.Build.Add(&withHeader{
                header: header,
                val: val,
            }, middleware.After)
        })
    }
}

func main() {
    cfg, err := config.LoadDefaultConfig(context.Background())
    if err != nil {
        // ...
    }

    svc := s3.NewFromConfig(cfg, WithHeader("x-user-header", "..."))
    // ...
}

ハンドラーフェーズ

SDK v2 ミドルウェアフェーズは、v1 ハンドラーフェーズの後継です。

次の表は、v1 ハンドラーフェーズと V2 ミドルウェアスタック内の同等の場所の大まかなマッピングを示しています。

v1 ハンドラー名	v2 ミドルウェアフェーズ
検証	Initialize
ビルド	シリアル化
Sign	確定
送信	該当なし (1)
ValidateResponse	逆シリアル化
マーシャリング解除	逆シリアル化
UnmarshalMetadata	逆シリアル化
UnmarshalError	逆シリアル化
再試行	`"Retry"` ミドルウェアの後に確定する (2)
AfterRetry	`"Retry"` ミドルウェアの前に、ポストを確定する`next.HandleFinalize()` (2,3)
CompleteAttempt	確定、ステップ終了
完了	初期化、ステップ開始、ポスト`next.HandleInitialize()` (3)

(1) v1 の Sendフェーズは、実質的に v2 のラップされた HTTP クライアントラウンドトリップです。この動作は、クライアントオプションの HTTPClientフィールドによって制御されます。

(2) Finalize ステップのミドルウェアの後の"Retry"ミドルウェアは、再試行ループの一部になります。

(3) オペレーション時のミドルウェア「スタック」は、繰り返しデコレートされたハンドラー関数に組み込まれています。各ハンドラーは、チェーン内の次のハンドラーを呼び出す責任があります。これは、ミドルウェアステップが次のステップが呼び出された後に、暗黙的にアクションを実行できることを意味します。

たとえば、スタックの上部にある初期化ステップの場合、次のハンドラーを呼び出した後にアクションを実行するミドルウェアを初期化すると、リクエストの最後に効果的に動作します。


// V2

import (
    "context"

    "github.com/aws/smithy-go/middleware"
)

type onComplete struct{}

var _ middleware.InitializeMiddleware = (*onComplete)(nil)

func (*onComplete) ID() string {
    return "onComplete"
}

func (*onComplete) HandleInitialize(ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler) (
    out middleware.InitializeOutput, metadata middleware.Metadata, err error,
) {
    out, metadata, err = next.HandleInitialize(ctx, in)

    // the entire operation was invoked above - the deserialized response is
    // available opaquely in out.Result, run post-op actions here...

    return out, metadata, err
}

機能

Amazon EC2 インスタンスメタデータサービス

AWS SDK for Go には、Amazon EC2 インスタンスでアプリケーションを実行するときにローカル IMDS をクエリするために使用できる Amazon EC2 インスタンスメタデータサービス (IMDS) クライアントが用意されています。IMDS クライアントは、を使用してアプリケーションに追加できる別の Go モジュールです。


go get github.com/aws/aws-sdk-go-v2/feature/ec2/imds

クライアントコンストラクタとメソッドオペレーションは、他の SDK サービスクライアントの設計に合わせて更新されました。

例


// V1

import "github.com/aws/aws-sdk-go/aws/ec2metadata"

// ...

client := ec2metadata.New(sess)

region, err := client.Region()
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/feature/ec2/imds"

// ...

client := imds.NewFromConfig(cfg)

region, err := client.GetRegion(context.TODO())
if err != nil {
    // handle error
}

Amazon S3 Transfer Manager

Amazon S3 転送マネージャーは、オブジェクトのアップロードとダウンロードを同時に管理できます。このパッケージは、サービスクライアントのインポートパス外の Go モジュールにあります。このモジュールは、を使用して取得できますgo get github.com/aws/aws-sdk-go-v2/feature/s3/manager。

s3.NewUploader と s3.NewUploaderWithClient は、コンストラクタメソッドマネージャーに置き換えられました。アップロードマネージャークライアントを作成するための NewUploader。

s3.NewDownloader と s3.NewDownloaderWithClient は、単一のコンストラクタメソッドマネージャーに置き換えられました。ダウンロードマネージャークライアントを作成するための NewDownloader。

Amazon CloudFront 署名ユーティリティ

AWS SDK for Go は、サービスクライアントのインポートパス外の Go モジュールに Amazon CloudFront 署名ユーティリティを提供します。このモジュールは、を使用して取得できますgo get。


go get github.com/aws/aws-sdk-go-v2/feature/cloudfront/sign

Amazon S3 暗号化クライアント

以降 AWS SDK for Go、Amazon S3 暗号化クライアントは AWS Crypto Tools の別のモジュールです。Go 用の S3 暗号化クライアントの最新バージョンである 3.x が https://github.com/aws/amazon-s3-encryption-client-go で利用可能になりました。このモジュールは、を使用して取得できますgo get。


go get github.com/aws/amazon-s3-encryption-client-go/v3

個別の EncryptionClient (v1、v2) API と DecryptionClient (v1、v2) APIs は、暗号化機能と復号機能の両方を公開する単一のクライアント S3EncryptionClientV3 に置き換えられました。

の他のサービスクライアントと同様に AWS SDK for Go、オペレーション APIs要約されています。

GetObject、GetObjectRequest、および GetObjectWithContext 復号 APIs は GetObject に置き換えられます。
PutObject、PutObjectRequest、および PutObjectWithContext暗号化 APIs は PutObject に置き換えられます。

暗号化クライアントの 3.x メジャーバージョンに移行する方法については、このガイドを参照してください。

サービスカスタマイズの変更

Amazon S3

v1 から AWS SDK for Go v2 に移行する場合、注意すべき重要な変更には、お客様が用意したキーによるサーバー側の暗号化 (SSE-C) SSECustomerKeyに使用されるの処理が含まれます。 AWS SDK for Go v1 では、Base64 SSECustomerKeyへののエンコーディングは SDK によって内部的に処理されました。SDK v2 では、この自動エンコードが削除され、SDK SSECustomerKeyに渡す前にを手動で Base64 にエンコードする必要があります。

調整の例：


// V1

import (
  "context"
  "encoding/base64"
  "github.com/aws/aws-sdk-go-v2/config"
  "github.com/aws/aws-sdk-go-v2/service/s3"
)
// ... more code

plainTextKey := "12345678901234567890123456789012" // 32 bytes in length

// calculate md5..

_, err = client.PutObjectWithContext(context.Background(), &s3.PutObjectInput{
    Bucket: aws.String("amzn-s3-demo-bucket"),
    Key:    aws.String("your-object-key"),
    Body:                 strings.NewReader("hello-world"),
    SSECustomerKey:       &plainTextKey,
    SSECustomerKeyMD5:    &base64Md5,
    SSECustomerAlgorithm: aws.String("AES256"),
})

// ... more code


// V2

import (
  "github.com/aws/aws-sdk-go/aws"
  "github.com/aws/aws-sdk-go/aws/session"
  "github.com/aws/aws-sdk-go/service/s3"
)

// ... more code

plainTextKey := "12345678901234567890123456789012" // 32 bytes in length
base64EncodedKey := base64.StdEncoding.EncodeToString([]byte(plainTextKey))

// calculate md5..

_, err = client.PutObject(context.Background(), &s3.PutObjectInput{
    Bucket: aws.String("amzn-s3-demo-bucket"),
    Key:    aws.String("your-object-key"),
    Body:                 strings.NewReader("hello-world"),
    SSECustomerKey:       &base64EncodedKey,
    SSECustomerKeyMD5:    &base64Md5,
    SSECustomerAlgorithm: aws.String("AES256"),
})

// ... more code

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

Amazon SQS

セキュリティ