HTTP インターセプター - AWS SDK for Go v2
インターセプターとミドルウェアの比較使用可能なインターセプターフックインターセプターの登録グローバルなインターセプター設定

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

HTTP インターセプター

インターセプターを使用して、API リクエストおよびレスポンスの実行フローにフックを挿入できます。インターセプターは、SDK がユーザー定義のコードを呼び出して、リクエスト/レスポンスのライフサイクルに処理を挿入できるようにする、柔軟な仕組みです。これにより、進行中のリクエストの変更、リクエスト処理のデバッグ、例外の確認などを行うことができます。

インターセプターとミドルウェアの比較

AWS SDK for Go v2 では、リクエスト処理をカスタマイズする手段として、インターセプターとミドルウェアの両方を提供しています。いずれも同様の目的に使用できますが、対象ユーザーやユースケースが異なります。

  • インターセプターは、HTTP 処理に特化したシンプルな API を使用してリクエスト/レスポンス処理をカスタマイズする SDK ユーザー向けに設計されています。インターセプターはリクエストライフサイクルの特定の段階にフックを挿入でき、HTTP リクエストおよびレスポンスを直接操作します。

  • ミドルウェアはより高度なシステムであり、トランスポートに依存しない設計となっており、主に SDK 内部で使用されます。ミドルウェアは強力な反面、SDK の内部構造に関する深い知識や、より複雑なインターフェイスの扱いが求められます。

一般的なユースケースにおいて、インターセプターがミドルウェアより優れている主な点は次のとおりです。

  • HTTP に特化: インターセプターは HTTP リクエストおよびレスポンスを直接扱うため、ミドルウェアに必要なトランスポート型の判定が不要です。

  • インターフェイスがシンプル: 各インターセプターフックは、特定の用途に特化したシンプルなインターフェイスを備えており、汎用的なミドルウェアとは異なる設計になっています。

  • 実行モデルが明確: インターセプターは、リクエストのライフサイクル中の明確に定義されたポイントで実行され、ミドルウェアスタックの順序を理解する必要がありません。

注記

インターセプターは既存のミドルウェアシステムの上に構築されており、両者は同じアプリケーション内で共存できます。ミドルウェアは、トランスポートに依存しない動作や複雑なスタック操作が必要な高度なユースケースに引き続き使用できます。

使用可能なインターセプターフック

AWS SDK for Go v2 では、リクエストライフサイクルのさまざまなステージで使用できるインターセプターフックを提供しています。各フックは、実装できる特定のインターフェイスに対応しています。

  • BeforeExecution - オペレーション実行時に最初に呼び出されるフック

  • BeforeSerialization - 入力メッセージがトランスポートリクエストにシリアル化される前

  • AfterSerialization - 入力メッセージがトランスポートリクエストにシリアル化された後

  • BeforeRetryLoop - 再試行ループに入る前

  • BeforeAttempt - 再試行ループ内で最初に呼び出されるフック

  • BeforeSigning - トランスポートリクエストが署名される前

  • AfterSigning - トランスポートリクエストが署名された後

  • BeforeTransmit - トランスポートリクエストが送信される前

  • AfterTransmit - トランスポートレスポンスを受信した後

  • BeforeDeserialization - トランスポートレスポンスが逆シリアル化される前

  • AfterDeserialization - トランスポートレスポンスがアンマーシャルされた後

  • AfterAttempt - 再試行ループ内で最後に呼び出されるフック

  • AfterExecution - オペレーション実行中に最後に呼び出されるフック

1 つのインターセプターで複数のインターフェイスを実装して、リクエストライフサイクルの複数のステージにフックを挿入できます。

インターセプターの登録

インターセプターは、サービスクライアントを作成するときや、特定のオペレーションの設定をオーバーライドするときに登録します。登録方法は、インターセプターをクライアントのすべてのオペレーションに適用するか、特定のオペレーションのみに適用するかによって異なります。

インターセプターは、追加および削除メソッドを備えた登録オブジェクトを通じて管理されます。次の例では、署名処理の前に送信リクエストに AWS X-Ray トレース ID ヘッダーを追加するシンプルなインターセプターを示しています。

type recursionDetection struct{}

func (recursionDetection) BeforeSigning(ctx context.Context, in *smithyhttp.InterceptorContext) error {
    if traceID := os.Getenv("_X_AMZN_TRACE_ID"); traceID != "" {
        in.Request.Header.Set("X-Amzn-Trace-Id", traceID)
    }
    return nil
}

// use it on the client
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.Interceptors.AddBeforeSigning(recursionDetection{})
})

インターセプターの登録オブジェクトはクライアントの Options に追加されて、オペレーションごとのインターセプター設定が可能になります。

// ... or use it per-operation
s3.ListBuckets(context.Background(), &s3.ListBucketsInput{
}, func(o *s3.Options) {
   o.Interceptors.AddBeforeSigning(recursionDetection{})
})

グローバルなインターセプター設定

また、各インターセプター型に対応する適切な config.LoadDefaultConfig オプションを指定して With* 関数を使用することで、インターセプターをグローバルに登録することもできます。これにより、その設定から作成されるすべての AWS サービスクライアントにインターセプターが適用されます。

type myExecutionInterceptor struct{}

func (*myExecutionInterceptor) AfterExecution(ctx context.Context, in *smithyhttp.InterceptorContext) error {
    // Add your custom logic here
    return nil
}

cfg, err := config.LoadDefaultConfig(context.Background(),
    config.WithAfterExecution(&myExecutionInterceptor{}))
if err != nil {
    panic(err)
}

// every service client created from the above config
// will include this interceptor
svc := s3.NewFromConfig(cfg)