Amazon API Gateway レスポンスストリーミングによる応答性の高い API の構築

本記事は2025年11月19日に公開された「Building responsive APIs with Amazon API Gateway response streaming」を翻訳したものです。

本日、AWS は Amazon API Gateway でレスポンスストリーミングのサポートを発表しました。これにより、レスポンスペイロードをクライアントに段階的にストリーミングすることで、REST API の応答性を大幅に向上させることができます。この新機能により、ストリーミングレスポンスを使用して、LLM 駆動アプリケーション (AI エージェントやチャットボットなど) を構築する際のユーザーエクスペリエンスを向上させたり、Web およびモバイルアプリケーションの time-to-first-byte (TTFB)パフォーマンスを改善したり、大きなファイルをストリーミングしたり、server-sent events (SSE) などのプロトコルを使用して段階的な進捗を報告しながら長時間実行される操作を実行したりできます。

この記事では、この新機能、それが対処する課題、およびレスポンスストリーミングを使用してアプリケーションの応答性を向上させる方法について説明します。

概要

次のシナリオを考えてみましょう。Amazon Bedrock の基盤モデルを使用する AI 駆動のエージェントアプリケーションを実行しているとします。ユーザーは API を介してアプリケーションと対話し、詳細な回答を必要とする複雑な質問をします。レスポンスストリーミング以前は、ユーザーはプロンプトを送信し、最終的にアプリケーションのレスポンスを受け取るまで待機する必要があり、場合によっては数十秒かかることもありました。この質問と回答の間の不自然な間は、切断された不自然なエクスペリエンスを生み出していました。

新しい API Gateway レスポンスストリーミング機能により、API を介した対話がはるかに流動的で自然なものになります。アプリケーションがモデルのレスポンスの処理を開始するとすぐに、API Gateway を使用してユーザーにストリーミングで返すことができます。

次のアニメーションは、この大幅なユーザーエクスペリエンスの向上を示しています。左側のプロンプトは非ストリーミングレスポンスを使用して処理され、ユーザーは結果を受け取るまで数秒待つ必要があります。右側のプロンプトは新しい API Gateway レスポンスストリーミングを使用しており、TTFB を大幅に削減し、ユーザーエクスペリエンスを向上させています。

図1. Bedrock 基盤モデルからレスポンスを返す際の API Gateway レスポンスストリーミング有効化前（左）と有効化後（右）のユーザーエクスペリエンスの比較

ユーザーは、誰かがタイピングしているのを見るように、AI のレスポンスが単語ごとにリアルタイムで表示されるのを確認できるようになりました。この即座のフィードバックにより、アプリケーションがよりレスポンシブで魅力的に感じられ、対話全体を通じてユーザーとの接続が維持されます。さらに、レスポンスサイズの制限を心配したり、複雑な回避策を実装したりする必要はありません。ストリーミングは自動的かつ効率的に行われるため、インフラストラクチャの制約を管理するのではなく、優れたユーザーエクスペリエンスの構築に集中できます。

レスポンスストリーミングの理解

従来のリクエスト・レスポンスモデルでは、レスポンスはクライアントに送信される前に完全に計算される必要があります。これはユーザーエクスペリエンスに悪影響を及ぼす可能性があります。クライアントは、サーバー側で完全なレスポンスが生成され、ネットワーク経由で送信されるまで待つ必要があります。これは、AI エージェント、チャットボット、バーチャルアシスタント、音楽ジェネレーターなどのインタラクティブでレイテンシーに敏感なクラウドアプリケーションで特に顕著です。

図2. レスポンスは完全に生成された後にのみクライアントに返され、time-to-first-byte レイテンシーが増加します

もう1つの重要なシナリオは、画像、大きなドキュメント、データセットなどの大きなレスポンスペイロードを返すことです。場合によっては、これらのペイロードが API Gateway の 10 MB のレスポンスサイズ制限またはデフォルトの統合タイムアウト制限である 29 秒を超える可能性があります。レスポンスストリーミングの開始前は、開発者は署名付き Amazon S3 URL を使用して大きなレスポンスをダウンロードしたり、タイムアウトの増加と引き換えに低い RPS を受け入れたりすることで、これらの制限を回避していました。機能的ではありますが、これらの回避策は追加のレイテンシーとアーキテクチャの複雑さをもたらしました。

レスポンスストリーミングのサポートにより、これらの課題に対処できます。REST API を更新してストリーミングレスポンスを返すことができるようになり、ユーザーエクスペリエンスを大幅に向上させ、TTFB パフォーマンスを改善し、10 MB を超えるレスポンスペイロードサイズをサポートし、最大 15 分かかるリクエストを処理できます。

図3. レスポンスストリーミングは最初のバイトまでの時間を短縮し、ユーザーエクスペリエンスを向上させます

レスポンスストリーミング機能は、すでに組織に大きなパフォーマンスをもたらしています。

「AWS チームと緊密に連携してレスポンスストリーミングを有効にすることは、Salesforce Commerce Cloud で最大の顧客に最もパフォーマンスの高いストアフロントエクスペリエンスを提供するためのロードマップを進める上で重要でした。私たちのコラボレーションは、Core Web Vital の目標を超えました。Total Blocking Time メトリクスが 98% 以上低下し、顧客がより高い収益とコンバージョン率を促進できるようになります」と、Salesforce のプロダクトマネジメントシニアディレクターである Drew Lau 氏は述べています。

レスポンスストリーミングは、任意の HTTP プロキシ統合、AWS Lambda 関数（プロキシ統合モードを使用）、およびプライベート統合でサポートされています。開始するには、次のセクションで説明するように、バックエンドからレスポンスをストリーミングするように API 統合を設定し、変更を有効にするために API を再デプロイします。

レスポンスストリーミングの開始

REST API のレスポンスストリーミングを有効にするには、統合設定を更新してレスポンス転送モードを STREAM に設定します。これにより、API Gateway はレスポンスバイトが利用可能になるとすぐにクライアントへのレスポンスのストリーミングを開始できます。レスポンスストリーミングを使用する場合、リクエストタイムアウトを最大 15 分まで設定できます。最初のバイトまでの時間を最適化するために、AWS はバックエンド統合もレスポンスストリーミングを実装することを強く推奨します。

次のスニペットに示すように、いくつかの異なる方法でレスポンスストリーミングを有効にできます。

API Gateway コンソールを使用して、メソッド統合を作成する際に、レスポンス転送モードで「ストリーム」を選択します。

図4. API Gateway コンソールでレスポンスストリーミングを有効にする

Open API 仕様を使用してレスポンス転送モードを設定する場合：

paths:
  /products:
    get:
      x-amazon-apigateway-integration:
        httpMethod: "GET"
        uri: "https://example.com"
        type: "http_proxy"
        timeoutInMillis: 300000
        responseTransferMode: "STREAM"

AWS CloudFormation などの Infrastructure as Code（IaC）フレームワークを使用してレスポンス転送モードを設定する場合、/response-streaming-invocations Uri フラグメントに注意してください。これは、Lambda InvokeWithResponseStreaming エンドポイントを使用するように API Gateway に指示します。

MyProxyResourceMethod:
  Type: 'AWS::ApiGateway::Method'
  Properties:
    RestApiId: !Ref LambdaSimpleProxy
    ResourceId: !Ref ProxyResource
    HttpMethod: ANY
    Integration:
      Type: AWS_PROXY
      IntegrationHttpMethod: POST
      ResponseTransferMode: STREAM
      Uri: !Sub arn:aws:apigateway:${APIGW_REGION}:lambda:path/2021-11-
           15/functions/${FN_ARN}/response-streaming-invocations

AWS CLI を使用してレスポンス転送モードを更新する場合：

aws apigw update-integration \
   --rest-api-id a1b2c2 \
   --resource-id aaa111 \
   --http-method GET \
   --patch-operations "op='replace',path='/responseTransferMode',value=STREAM" \
   --region us-west-2

Lambda 関数でのレスポンスストリーミングの使用

Lambda 関数をダウンストリーム統合エンドポイントとして使用する場合、Lambda 関数はストリーミング対応である必要があります。次の図に示すように、API Gateway は InvokeWithResponseStreaming API を使用して関数を呼び出し、Lambda プロキシ統合が必要です。詳細については、API Gateway ドキュメントを参照してください。

図5. インタラクティブな AI アプリケーション用の Lambda 関数での API Gateway レスポンスストリーミングの使用

Lambda 関数でレスポンスストリーミングを使用する場合、API Gateway はハンドラーレスポンスストリームに次のコンポーネントが（順番に）含まれることを期待します。

JSON レスポンスメタデータ – 有効な JSON オブジェクトである必要があり、statusCode、headers、multiValueHeaders、および cookies フィールド（すべてオプション）のみを含めることができます。メタデータは空の文字列にすることはできません。少なくとも空の JSON オブジェクトである必要があります。
8 バイトの null 区切り文字 – 以下に示すように、組み込みの awslambda.HttpResponseStream.from() メソッドを使用すると、Lambda がこの区切り文字を自動的に追加します。このメソッドを使用しない場合は、自分で区切り文字を追加する必要があります。
レスポンスペイロード – 空にすることができます。

次のコードスニペットは、API Gateway レスポンスストリーミングと互換性があるように Lambda 関数からストリーミングレスポンスを返す方法を示しています。

export const handler = awslambda.streamifyResponse(
   async (event, responseStream, context) => {

      const httpResponseMetadata = {
         statusCode: 200,
         headers: {
            'Content-Type': 'text/plain',
            'X-Custom-Header': 'some-value'
         }
      };

      responseStream = awslambda.HttpResponseStream.from(
         responseStream,
         httpResponseMetadata
      );

      responseStream.write('hello');
      await new Promise(r => setTimeout(r, 1000));
      responseStream.write(' world');
      await new Promise(r => setTimeout(r, 1000));
      responseStream.write('!!!');
      responseStream.end();
   }
);

詳細な実装ガイドラインについては、API Gateway ドキュメントを参照してください。

HTTP プロキシ統合でのレスポンスストリーミングの使用

ダウンストリーム統合エンドポイントとして使用されるアプリケーション（たとえば、Amazon Elastic Container Service（Amazon ECS）または Amazon Elastic Kubernetes Service（Amazon EKS）で実行されている Web サーバー）から HTTP レスポンスをストリーミングできます。この場合、HTTP_PROXY 統合を使用し、レスポンス転送モードを STREAM として指定する必要があります（コンソール、AWS CLI、または IaC を使用）。API を変更した後、再デプロイします。

図6. HTTP サーバーアプリケーションでの API Gateway レスポンスストリーミングの使用

API Gateway がアプリケーションからストリーミングレスポンスを受信すると、HTTP ヘッダーブロックの転送が完了するまで待機します。次に、クライアントに HTTP レスポンスステータスコードとヘッダーを送信し、その後、API Gateway サービスが受信したアプリケーションからのコンテンツを送信します。ストリームが終了するまで（最大 15 分）、アプリケーションからクライアントへのレスポンスのストリーミングを続けます。

多くの一般的な API および Web アプリケーション開発フレームワークは、レスポンスストリーミングの抽象化を提供しています。次のコードスニペットは、FastAPI を使用して HTTP レスポンスストリーミングを実装する方法を示しています。

app = FastAPI()

async def stream_response():
   yield b"Hello "
   await asyncio.sleep(1)
   yield b"World "
   await asyncio.sleep(1)
   yield b"!"

@app.get("/")
async def main():
   return StreamingResponse(stream_response(), media_type="text/plain")

HTTP クライアントへのリアルタイムレスポンスストリーミングの追加

HTTP クライアントによって、到着したストリーミングレスポンスフラグメントを処理する方法が異なります。次のコードスニペットは、Node.js アプリケーションでストリーミングレスポンスを処理する方法を示しています。

const request = http.request(options, (response)=>{
   response.on('data', (chunk) => {
      console.log(chunk);
   });

   response.on('end', () => {
      console.log('Response complete');
   });
});

request.end();

CURL を使用する場合、–no-buffer 引数を使用して、到着したレスポンスフラグメントを出力できます。

curl --no-buffer {URL}

サンプルコード

GitHub からこのサンプルプロジェクトをクローンして、API Gateway レスポンスストリーミングの動作を確認してください。README.md の手順に従って、AWS アカウントにサンプルプロジェクトをプロビジョニングします。

考慮事項

レスポンスストリーミングを有効にする前に、次の点を考慮してください。

レスポンスストリーミングは REST API で利用でき、HTTP_PROXY 統合、Lambda 統合（プロキシモード）、およびプライベート統合で使用できます。
API Gateway レスポンスストリーミングは、リージョナル、プライベート、エッジ最適化などの任意のエンドポイントタイプで、カスタムドメイン名の有無にかかわらず使用できます。
レスポンスストリーミングを使用する場合、シナリオの要件に応じて、レスポンスタイムアウトを最大 15 分まで設定できます。
リージョナルまたはプライベートエンドポイントからのすべてのストリーミングレスポンスには、5 分のアイドルタイムアウトが適用されます。エッジ最適化エンドポイントからのすべてのストリーミングレスポンスには、30 秒のアイドルタイムアウトが適用されます。
各ストリーミングレスポンス内で、最初の 10 MB のレスポンスペイロードには帯域幅制限はありません。10 MB を超えるレスポンスペイロードデータは、2 MB/秒に制限されます。
レスポンスストリーミングは、オーソライザー、WAF、アクセス制御、TLS/mTLS、リクエストスロットリング、およびアクセスログなどの API Gateway セキュリティ機能と互換性があります。
ストリーミングレスポンスを処理する場合、次の機能はサポートされていません：VTL によるレスポンス変換、統合レスポンスキャッシング、およびコンテンツエンコーディング。
Lambda オーソライザーまたは Amazon Cognito ユーザープールで適切な認可を実装することにより、不正アクセスやその他の潜在的なセキュリティ脅威から API を常に保護してください。詳細については、REST API 保護ドキュメントおよび API Gateway セキュリティドキュメントを参照してください。

オブザーバビリティ

実行ログ、アクセスログ、AWS X-Ray 統合、および Amazon CloudWatch メトリクスなどの既存のオブザーバビリティ機能を、API Gateway レスポンスストリーミングで引き続き使用できます。

既存のアクセスログ変数に加えて、次の新しい変数が利用可能です。

$content.integration.responseTransferMode – 統合のレスポンス転送モード。BUFFERED または STREAMED のいずれかです。
$context.integration.timeToAllHeaders – API Gateway が統合接続を確立してから、クライアントからすべての統合レスポンスヘッダーを受信するまでの時間。
$context.integration.timeToFirstContent – API Gateway が統合接続を確立してから、最初のコンテンツバイトを受信するまでの時間。

詳細については、API Gateway ドキュメントを参照してください。

料金

この新機能により、ストリーミングレスポンスに対して同じ API 呼び出し料金を引き続き支払います。10 MB のレスポンスデータごとに、最も近い 10 MB に切り上げられ、1 つのリクエストとして請求されます。詳細については、API Gateway 料金ページを参照してください。

まとめ

Amazon API Gateway の新しいレスポンスストリーミング機能により、クラウドで応答性の高い API を構築および提供する方法が強化されます。レスポンスデータが利用可能になるとすぐにストリーミングすることで、最初のバイトまでの時間のパフォーマンスを大幅に改善し、従来のペイロードサイズとタイムアウトの制限を克服できます。これは、リアルタイムの応答性を必要とする AI 駆動アプリケーション、ファイル転送、およびインタラクティブな Web エクスペリエンスに特に価値があります。

API Gateway レスポンスストリーミングの詳細については、サービスドキュメントを参照してください。

サーバーレスアーキテクチャの構築の詳細については、Serverless Land を参照してください。

Amazon Web Services ブログ

Amazon API Gateway レスポンスストリーミングによる応答性の高い API の構築

概要

レスポンスストリーミングの理解

レスポンスストリーミングの開始

Lambda 関数でのレスポンスストリーミングの使用

HTTP プロキシ統合でのレスポンスストリーミングの使用

HTTP クライアントへのリアルタイムレスポンスストリーミングの追加

サンプルコード

考慮事項

オブザーバビリティ

料金

まとめ

お役立ちリンク

フォローお願いいたします

学ぶ

リソース

デベロッパー

ヘルプ