HTTP エンドポイント配信リクエストとレスポンスの仕様を理解する

Amazon Data Firehose がカスタムHTTPエンドポイントにデータを正常に配信するには、これらのエンドポイントがリクエストを受け入れ、特定の Amazon Data Firehose リクエストおよびレスポンス形式を使用してレスポンスを送信する必要があります。このセクションでは、Amazon Data Firehose サービスがカスタムHTTPエンドポイントに送信するHTTPリクエストの形式仕様と、Amazon Data Firehose サービスが期待するHTTPレスポンスの形式仕様について説明します。HTTP エンドポイントは、Amazon Data Firehose がそのリクエストをタイムアウトする前に、リクエストに応答するまで 3 分かかります。Amazon Data Firehose は、適切な形式に従わないレスポンスを配信失敗として扱います。

リクエストの形式

パスとURLパラメータ

これらは 1 つのURLフィールドの一部として直接設定されます。Amazon Data Firehose は、変更なしで設定どおりに送信します。https 送信先のみがサポートされます。URL 制限は、配信ストリームの設定時に適用されます。

注記

現在、HTTPエンドポイントデータ配信ではポート 443 のみがサポートされています。

HTTP ヘッダー - X-Amz-Firehose-Protocol-Version

このヘッダーは、リクエスト/レスポンス形式のバージョンを示すために使用されます。現在バージョンは 1.0 のみです。

HTTP ヘッダー - X-Amz-Firehose-Request-Id

このヘッダーの値は、デバッグおよび重複排除の目的でGUID使用できる不透明です。エンドポイントの実装では、成功したリクエストと失敗したリクエストの両方について、可能であれば、このヘッダーの値をログ記録する必要があります。リクエスト ID は、同じリクエストを複数回試行しても同じに保たれます。

HTTP ヘッダー - Content-Type

Content-Type ヘッダーの値は常に application/json です。

HTTP ヘッダー - コンテンツエンコーディング

Firehose ストリームは、リクエストの送信時に本文を圧縮GZIPするためにを使用するように設定できます。この圧縮を有効にすると、標準的な方法に従って Content-Encoding ヘッダーの値は gzip に設定されます。圧縮が有効にされない場合、Content-Encoding ヘッダーはまったく存在しません。

HTTP ヘッダー - Content-Length

これは標準的な方法で使用されます。

HTTP ヘッダー - X-Amz-Firehose-Source-Arn:

ASCII 文字列形式で表される Firehose ストリームARNの。ARN エンコードリージョン、 AWS アカウント ID、ストリーム名。例えば、arn:aws:firehose:us-east-1:123456789:deliverystream/testStream と指定します。

HTTP ヘッダー - X-Amz-Firehose-Access-Key

このヘッダーには、 API キーまたはその他の認証情報が保持されます。deliveryAPI-stream を作成または更新するときに、キー (認証トークン) を作成または更新できます。Amazon Data Firehose は、アクセスキーのサイズを 4096 バイトに制限します。Amazon Data Firehose は、このキーを解釈しようとしません。設定されたキーは、このヘッダーの値に逐語的にコピーされます。

コンテンツは任意であり、JWTトークンまたは ACCESS_ を表す可能性がありますKEY。エンドポイントがマルチフィールド認証情報 (ユーザー名やパスワードなど) を必要とする場合、すべてのフィールドの値は、エンドポイントが理解する形式 (JSON または ) で 1 つのアクセスキー内にまとめて保存する必要がありますCSV。元の内容がバイナリである場合、このフィールドは base-64 でエンコードできます。Amazon Data Firehose は、設定値を変更および/またはエンコードせず、コンテンツをそのまま使用します。

HTTP ヘッダー - X-Amz-Firehose-Common-Attributes

このヘッダーは、リクエスト全体やリクエスト内のすべてのレコードに関連する共通の属性 (メタデータ) を保持します。これらは、Firehose ストリームを作成するときにユーザーが直接設定します。この属性の値は、次のスキーマを持つJSONオブジェクトとしてエンコードされます。



"$schema": http://json-schema.org/draft-07/schema#

properties:
  commonAttributes:
    type: object
    minProperties: 0
    maxProperties: 50
    patternProperties:
      "^.{1,256}$":
        type: string
        minLength: 0
        maxLength: 1024

例を示します。



"commonAttributes": {
    "deployment -context": "pre-prod-gamma",
    "device-types": ""
  }

本文 - 最大サイズ

最大本文サイズはユーザーによって設定され、圧縮前に最大 64 MiB まで設定できます。

本文 - スキーマ

本文には、次のJSONスキーマ ( で記述) を含む 1 つのJSONドキュメントがありますYAML。



"$schema": http://json-schema.org/draft-07/schema#

title: FirehoseCustomHttpsEndpointRequest
description: >
  The request body that the Firehose service sends to
  custom HTTPS endpoints.
type: object
properties:
  requestId:
    description: >
      Same as the value in the X-Amz-Firehose-Request-Id header,
      duplicated here for convenience.
    type: string
  timestamp:
    description: >
      The timestamp (milliseconds since epoch) at which the Firehose
      server generated this request.
    type: integer
  records:
    description: >
      The actual records of the Firehose stream, carrying 
      the customer data.
    type: array
    minItems: 1
    maxItems: 10000
    items:
      type: object
      properties:
        data:
          description: >
            The data of this record, in Base64. Note that empty
            records are permitted in Firehose. The maximum allowed
            size of the data, before Base64 encoding, is 1024000
            bytes; the maximum length of this field is therefore
            1365336 chars.
          type: string
          minLength: 0
          maxLength: 1365336

required:
  - requestId
  - records

例を示します。



{
  "requestId": "ed4acda5-034f-9f42-bba1-f29aea6d7d8f",
  "timestamp": 1578090901599
  "records": [
    {
      "data": "aGVsbG8="
    },
    {
      "data": "aGVsbG8gd29ybGQ="
    }
  ]
}

レスポンスの形式

エラー時のデフォルトの動作

レスポンスが以下の要件に適合しない場合、Firehose サーバーは、本文のない 500 ステータスコードであるかのように扱います。

ステータスコード

HTTP ステータスコードMUSTは 2XX, 4XXまたは 5XX の範囲です。

Amazon Data Firehose サーバーはリダイレクト (3XX ステータスコード) NOTに従います。レスポンスコード 200 のみが、HTTP/EP へのレコードの正常な配信と見なされます。レスポンスコード 413 (サイズを超過) は永続的な障害と見なされ、レコードバッチが設定されている場合、エラーバケットに送信されません。その他のすべてのレスポンスコードは、再試行可能なエラーとみなされ、後で説明するバックオフ再試行アルゴリズムの対象となります。

ヘッダー - コンテンツタイプ

許容できるコンテンツタイプは application/json です。

HTTP ヘッダー - コンテンツエンコーディング

Content-Encoding MUSTNOTが使用されます。本文MUSTは解凍されます。

HTTP ヘッダー - Content-Length

レスポンスに本文がある場合はMUST、Content-Length ヘッダーが表示されます。

本文 - 最大サイズ

レスポンス本文のサイズは 1 MiB 以下である必要があります。



"$schema": http://json-schema.org/draft-07/schema#

title: FirehoseCustomHttpsEndpointResponse

description: >
  The response body that the Firehose service sends to
  custom HTTPS endpoints.
type: object
properties:
  requestId:
    description: >
      Must match the requestId in the request.
    type: string
  
  timestamp:
    description: >
      The timestamp (milliseconds since epoch) at which the
      server processed this request.
    type: integer
   
  errorMessage:
    description: >
      For failed requests, a message explaining the failure.
      If a request fails after exhausting all retries, the last 
      Instance of the error message is copied to error output
      S3 bucket if configured.
    type: string
    minLength: 0
    maxLength: 8192
required:
  - requestId
  - timestamp

例を示します。



Failure Case (HTTP Response Code 4xx or 5xx)
{
  "requestId": "ed4acda5-034f-9f42-bba1-f29aea6d7d8f",
  "timestamp": "1578090903599",
  "errorMessage": "Unable to deliver records due to unknown error."
}
Success case (HTTP Response Code 200)
{
  "requestId": "ed4acda5-034f-9f42-bba1-f29aea6d7d8f",
  "timestamp": 1578090903599
}

エラーレスポンスの処理

すべてのエラーケースで、Amazon Data Firehose サーバーはエクスポネンシャルバックオフアルゴリズムを使用してレコードの同じバッチの配信を再試行します。再試行は、ジッター係数 (15%) の初期バックオフ時間 (1 秒) を使用してバックオフされ、後続の各再試行は、ジッターが追加された式 (initial-backoff-time * (乗数 (2) ^ retry_count)) を使用してバックオフされます。バックオフ時間は最大 2 分間隔で制限されます。例えば、「n」回目の再試行では、バックオフ時間は = MAX(120, 2^n) * random(0.85, 1.15) です。

前の数式で指定されたパラメータは変更の対象となります。エクスポネンシャルバックオフアルゴリズムで使用される正確な初期バックオフ時間、最大バックオフ時間、乗数、ジッターの割合については、 AWS Firehose のドキュメントを参照してください。

後続の再試行ごとに、レコードが配信されるアクセスキーや送信先が、Firehose ストリームの更新された設定に基づいて変更される可能性があります。Amazon Data Firehose サービスは、ベストエフォート方式で再試行間で同じ request-id を使用します。この最後の機能は、HTTPエンドポイントサーバーによる重複排除の目的で使用できます。リクエストが (Firehose ストリーム設定に基づいて) 許容される最大時間経過後も配信されない場合、オプションで、ストリーム設定に基づいてレコードのバッチをエラーバケットに配信できます。

例

CWLog ソースリクエストの例。



{
  "requestId": "ed4acda5-034f-9f42-bba1-f29aea6d7d8f",
  "timestamp": 1578090901599,
  "records": [
   {
    "data": {
      "messageType": "DATA_MESSAGE",
      "owner": "123456789012",
      "logGroup": "log_group_name",
      "logStream": "log_stream_name",
      "subscriptionFilters": [
        "subscription_filter_name"
      ],
      "logEvents": [
        {
          "id": "0123456789012345678901234567890123456789012345",
          "timestamp": 1510109208016,
          "message": "log message 1"
        },
        {
          "id": "0123456789012345678901234567890123456789012345",
          "timestamp": 1510109208017,
          "message": "log message 2"
        }
      ]
    }
   }
  ]
}

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

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

ドキュメントの表記規則

AWS アカウントとリージョン間の配信を理解する

データ配信の失敗を処理する