HTTP 엔드포인트 전송 요청 및 응답 사양에 대한 이해

Amazon Data Firehose가 사용자 지정 HTTP 엔드포인트에 데이터를 성공적으로 전송하기 위해서는 이러한 엔드포인트가 특정 Amazon Data Firehose 요청 및 응답 형식을 사용하여 요청을 수락하고 응답을 보내야 합니다. 이 섹션에서는 Amazon Data Firehose 서비스가 사용자 지정 HTTP 엔드포인트에 보내는 HTTP 요청의 형식 사양과 Amazon Data Firehose 서비스가 예상하는 HTTP 응답의 형식 사양에 대해 설명합니다. Amazon Data Firehose에서 요청 제한 시간을 초과하기 전까지 HTTP 엔드포인트는 3분 이내에 요청에 응답해야 합니다. Amazon Data Firehose는 알맞은 형식을 준수하지 않는 응답을 전송 실패로 간주합니다.

요청 형식

경로 및 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

요청을 전송할 때 GZIP을 사용하여 본문을 압축하도록 Firehose 스트림을 구성할 수 있습니다. 이 압축이 활성화되면, 표준 관행에 따라 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 키 또는 다른 자격 증명이 포함됩니다. 전송 스트림을 만들거나 업데이트할 때 API 키(인증 토큰)를 만들거나 업데이트할 수 있습니다. Amazon Data Firehose는 액세스 키의 크기를 4,096바이트로 제한합니다. Amazon Data Firehose는 어떤 방식으로도 이 키를 해석하려는 시도를 하지 않습니다. 구성된 키는 그대로 이 헤더 값에 복사됩니다.

그 내용은 임의적이며 JWT 토큰 또는 ACCESS_KEY를 나타낼 가능성이 있습니다. 엔드포인트에 다중 필드 자격 증명(예: 사용자 이름 및 암호) 이 필요한 경우, 모든 필드의 값을 엔드포인트가 인식하는 형식(JSON 또는 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": ""
  }

본문 - 최대 크기

최대 본문 크기는 사용자가 구성하며 압축 전 최대 64MiB까지 가능합니다.

본문 - 스키마

본문에는 다음과 같은 JSON Schema(YAML로 작성)를 사용한 단일 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(크기 초과)은 영구 실패로 간주되며, 이 코드가 구성되면 레코드 배치가 오류 버킷으로 전송되지 않습니다. 다른 모든 응답 코드는 재시도 가능한 오류로 간주되며, 이후 설명할 백오프 재시도 알고리즘이 적용됩니다.

헤더 – 콘텐츠 유형

허용되는 유일한 콘텐츠 유형은 애플리케이션/json입니다.

HTTP 헤더 - Content-Encoding

콘텐츠 인코딩은 사용하지 않아야 합니다. 본문은 반드시 압축을 풀어야 합니다.

HTTP 헤더 - Content-Length

응답에 본문이 있는 경우 반드시 Content-Length 헤더가 있어야 합니다.

본문 - 최대 크기

응답 본문의 크기는 1MiB 이하여야 합니다.



"$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초)을 사용하여 재시도가 백오프되고, 이후 재시도할 때마다 지터가 추가된 공식(초기 백오프 시간* (승수(2) ^ retry_count))을 사용하여 백오프됩니다. 백오프 시간은 최대 2분 간격으로 제한됩니다. 예를 들어, 'n번째 재시도' 시 백오프 시간은 최대(120, 2^n) * 무작위(0.85, 1,15)입니다.

이전 방정식에서 지정된 파라미터는 변경될 수 있습니다. 지수 백오프 알고리즘에 사용되는 정확한 초기 백오프 시간, 최대 백오프 시간, 승수, 지터 백분율은 AWS Firehose 설명서를 참조하세요.

이후에 다시 시도할 때마다 레코드가 전송되는 액세스 키 및/또는 대상은 업데이트된 Firehose 스트림 구성에 따라 변경될 수 있습니다. Amazon Data Firehose 서비스는 최선의 방법으로 여러 번의 재시도에 걸쳐 동일한 요청 ID(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 계정 및 리전 간 전송 이해

데이터 전송 실패 처리