Lampiran - Spesifikasi Permintaan dan Respons Pengiriman Titik Akhir HTTP

Agar Amazon Data Firehose berhasil mengirimkan data ke titik akhir HTTP kustom, titik akhir ini harus menerima permintaan dan mengirim tanggapan menggunakan format permintaan dan respons Amazon Data Firehose tertentu. Bagian ini menjelaskan spesifikasi format permintaan HTTP yang dikirim oleh layanan Amazon Data Firehose ke titik akhir HTTP kustom, serta spesifikasi format respons HTTP yang diharapkan oleh layanan Amazon Data Firehose. Titik akhir HTTP memiliki waktu 3 menit untuk menanggapi permintaan sebelum Amazon Data Firehose menghentikan permintaan tersebut. Amazon Data Firehose memperlakukan respons yang tidak sesuai dengan format yang tepat sebagai kegagalan pengiriman.

Format Permintaan

Parameter Jalur dan URL

Ini dikonfigurasi secara langsung oleh Anda sebagai bagian dari bidang URL tunggal. Amazon Data Firehose mengirimkannya seperti yang dikonfigurasi tanpa modifikasi. Hanya tujuan https yang didukung. Pembatasan URL diterapkan selama konfigurasi aliran pengiriman.

catatan

Saat ini, hanya port 443 yang didukung untuk pengiriman data titik akhir HTTP.

Header HTTP - X-Amz-Firehose-Protocol-Version

Header ini digunakan untuk menunjukkan versi format permintaan/respons. Saru-satunya versi saat ini adalah 1.0.

Header HTTP - X-Amz-Firehose-Request-Id

Nilai header ini adalah GUID buram yang dapat digunakan untuk tujuan debugging dan deduplikasi. Implementasi titik akhir harus mencatat nilai header ini jika memungkinkan, baik permintaan sukses maupun gagal. ID permintaan tetap sama di antara beberapa upaya permintaan yang sama.

Header HTTP - Content-Type

Nilai header Content-Type selalu application/json.

Header HTTP - Content-Encoding

Aliran Firehose dapat dikonfigurasi untuk menggunakan GZIP untuk mengompres tubuh saat mengirim permintaan. Ketika kompresi ini diaktifkan, nilai header Content-Encoding diatur ke gzip, sesuai praktek standar. Jika kompresi tidak diaktifkan, header Content-Encoding tidak ada sama sekali.

Header HTTP - Content-Length

Ini digunakan dengan cara standar.

Header HTTP - X-Amz-Firehose-Source-Arn:

ARN dari aliran Firehose diwakili dalam format string ASCII. ARN mengkodekan wilayah, ID AWS akun, dan nama aliran. Misalnya, arn:aws:firehose:us-east-1:123456789:deliverystream/testStream.

Header HTTP - X-Amz-Firehose-Access-Key

Header ini membawa kunci API atau kredensial lainnya. Anda memiliki kemampuan untuk membuat atau memperbarui kunci API (alias token otorisasi) saat membuat atau memperbarui aliran pengiriman Anda. Amazon Data Firehose membatasi ukuran kunci akses ke 4096 byte. Amazon Data Firehose tidak mencoba menafsirkan kunci ini dengan cara apa pun. Kunci yang dikonfigurasi disalin secara verbatim ke nilai header ini.

Isi bisa berubah-ubah dan berpotensi mewakili token JWT atau ACCESS_KEY. Jika titik akhir memerlukan kredensial multi-bidang (misalnya, nama pengguna dan kata sandi), nilai semua bidang harus disimpan bersama-sama dalam satu access key dalam format yang dimengerti titik akhir (JSON atau CSV). Bidang ini dapat berupa dikodekan basis-64 jika isi asli bersifat biner. Amazon Data Firehose tidak memodifikasi dan/atau menyandikan nilai yang dikonfigurasi dan menggunakan konten apa adanya.

Header HTTP - X-Amz-Firehose-Common-Attributes

Header ini membawa atribut umum (metadata) yang berkaitan dengan seluruh permintaan, dan/atau semua catatan dalam permintaan. Ini dikonfigurasi langsung oleh Anda saat membuat aliran Firehose. Nilai atribut ini dikodekan sebagai objek JSON dengan skema berikut:



"$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

Inilah contohnya:



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

Isi - Ukuran Maks

Ukuran isi maksimum dikonfigurasi oleh Anda, dan bisa sampai maksimal 64 MiB, sebelum kompresi.

Isi - Skema

Isi membawa satu dokumen JSON dengan Skema JSON berikut (ditulis dalam 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

Inilah contohnya:



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

Format Respons

Perilaku Default pada Galat

Jika respons gagal memenuhi persyaratan di bawah ini, server Firehose memperlakukannya seolah-olah memiliki kode status 500 tanpa isi.

Kode Status

Kode status HTTP HARUS berada di kisaran 2XX, 4XX, atau 5XX.

Server Amazon Data Firehose TIDAK mengikuti pengalihan (kode status 3XX). Hanya kode respons 200 yang dianggap sebagai pengiriman catatan yang sukses untuk HTTP/EP. Kode respons 413 (ukuran melebihi) dianggap sebagai kegagalan permanen dan kumpulan catatan tidak dikirim ke bucket kesalahan jika dikonfigurasi. Semua kode respons lainnya dianggap sebagai kesalahan yang bisa dicoba ulang dan dikenakan algoritma mundur coba lagi yang akan dijelaskan kemudian.

Header HTTP - Jenis Konten

Satu-satunya jenis konten yang dapat diterima adalah aplikasi/json.

Header HTTP - Content-Encoding

Content-Encoding TIDAK HARUS digunakan. Isi HARUS tidak dikompresi.

Header HTTP - Content-Length

Header Content-Length HARUS ada jika respons memiliki isi.

Isi - Ukuran Maks

Isi respons harus berukuran 1 MiB atau kurang.



"$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

Inilah contohnya:



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
}

Penanganan Respons Kesalahan

Dalam semua kasus kesalahan, server Amazon Data Firehose mencoba kembali pengiriman kumpulan catatan yang sama menggunakan algoritma back-off eksponensial. Percobaan ulang dibatalkan menggunakan waktu mundur awal (1 detik) dengan faktor jitter (15%) dan setiap percobaan ulang berikutnya dibatalkan menggunakan rumus (initial-backoff-time * (pengganda (2) ^ retry_count)) dengan jitter tambahan. Waktu mundur dibatasi oleh interval maksimum 2 menit. Misalnya pada percobaan ulang 'n'-th, waktu mundur adalah = MAX (120, 2^n) * acak (0,85, 1,15).

Parameter yang ditentukan dalam persamaan sebelumnya dapat berubah sewaktu-waktu. Lihat dokumentasi AWS Firehose untuk mengetahui waktu mundur awal yang tepat, waktu backoff maks, persentase pengganda, dan jitter yang digunakan dalam algoritma mundur eksponensial.

Dalam setiap percobaan ulang berikutnya, kunci akses dan/atau tujuan ke mana catatan dikirimkan dapat berubah berdasarkan konfigurasi aliran Firehose yang diperbarui. Layanan Amazon Data Firehose menggunakan id permintaan yang sama di seluruh percobaan ulang dengan upaya terbaik. Fitur terakhir ini dapat digunakan untuk tujuan deduplikasi oleh server titik akhir HTTP. Jika permintaan masih belum dikirimkan setelah waktu maksimum yang diizinkan (berdasarkan konfigurasi aliran Firehose), kumpulan rekaman secara opsional dapat dikirim ke bucket kesalahan berdasarkan konfigurasi aliran.

Contoh

Contoh permintaan bersumber 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"
        }
      ]
    }
   }
  ]
}

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Kuota

Riwayat Dokumen