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

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

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

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

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

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

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

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

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

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

このヘッダーは、リクエスト全体やリクエスト内のすべてのレコードに関連する共通の属性 (メタデータ) を保持します。これらは、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 スキーマ (YAML で記述) を持つ 1 つの JSON ドキュメントが含まれます。

"$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 ステータスコードは 2XX、4XX、または 5XX でなければなりませんす。

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

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

Content-Encoding は使用しないでください。本文は圧縮解除しなければなりません。

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 * (multiplier(2) ^ retry_count)) を使用してバックオフされます。バックオフ時間は最大 2 分間隔で制限されます。例えば、「n」回目の再試行では、バックオフ時間は = MAX(120, 2^n) * random(0.85, 1.15) となります。

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

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