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

# HTTP エンドポイント配信リクエストとレスポンスの仕様を理解する
<a name="httpdeliveryrequestresponse"></a>

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

## リクエストの形式
<a name="requestformat"></a>

**パスと URL パラメータ**  
これらは、単一の 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 ヘッダー - Content-Encoding**  
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 キーまたはその他の認証情報を運びます。delivery-stream を作成または更新するときに、API キー (別名、認可トークン) を作成または更新できます。Amazon Data Firehose では、アクセスキーのサイズが 4096 バイトに制限されます。Amazon Data Firehose は、このキーを一切解釈しようとしません。設定されたキーは、このヘッダーの値に逐語的にコピーされます。ただし、Secrets Manager を使用してキーを設定する場合、シークレットは特定の JSON オブジェクト形式 `{"api_key": "..."}` に従う必要があります。  
コンテンツは任意であり、JWT トークンまたは ACCESS\$1KEY を表すことができます。エンドポイントで複数フィールドの認証情報 (ユーザー名やパスワードなど) が必要な場合は、すべてのフィールドの値を、エンドポイントが認識できる形式 (JSON または CSV) で 1 つのアクセスキー内にまとめて保存する必要があります。元の内容がバイナリである場合、このフィールドは 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 スキーマ (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="
    }
  ]
}
```

## レスポンスの形式
<a name="responseformat"></a>

**エラー時のデフォルトの動作**  
レスポンスが以下の要件に適合しない場合、Firehose サーバーは本文なしで 500 ステータスコードがあるかのように処理します。

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

**ヘッダー - コンテンツタイプ**  
許容できるコンテンツタイプは application/json です。

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

**HTTP ヘッダー - Content-Length**  
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 \$1 (multiplier(2) ^ retry\$1count)) を使用してバックオフされます。バックオフ時間は最大 2 分間隔で制限されます。例えば、「n」回目の再試行では、バックオフ時間は = MAX(120, 2^n) \$1 random(0.85, 1.15) となります。  
前の数式で指定されたパラメータは変更の対象となります。エクスポネンシャルバックオフアルゴリズムで使用される正確な初期バックオフ時間、最大バックオフ時間、乗数、ジッターの割合については、 AWS Firehose のドキュメントを参照してください。  
その後の再試行ごとに、レコードが配信されるアクセスキーや宛先が、Firehose ストリームの更新された設定に基づいて変更される場合があります。Amazon Data Firehose サービスは、再試行全体で同じリクエスト ID をベストエフォート方式で使用します。この最後の機能は、HTTP エンドポイントサーバーによる重複排除の目的で使用できます。許容される最大時間 (Firehose ストリーム設定に基づく) 後にリクエストが配信されない場合は、ストリーム設定に基づいてレコードのバッチをオプションでエラーバケットに配信できます。

## 例
<a name="examples"></a>

 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"
        }
      ]
    }
   }
  ]
}
```