Memahami permintaan pengiriman HTTP titik akhir dan spesifikasi respons

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

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

Nilai header ini adalah buram GUID 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.

Nilai header Content-Type selalu application/json.

Aliran Firehose dapat dikonfigurasi untuk digunakan 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.

Ini digunakan dengan cara standar.

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

Header ini membawa API kunci atau kredensi lainnya. Anda memiliki kemampuan untuk membuat atau memperbarui API -key (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.

Konten dapat sewenang-wenang dan berpotensi mewakili JWT token atau ACCESS _KEY. Jika titik akhir memerlukan kredensi multi-bidang (misalnya, nama pengguna dan kata sandi), nilai semua bidang harus disimpan bersama dalam satu kunci akses dalam format yang dipahami titik akhir (atau). JSON CSV Bidang ini dapat berupa dikodekan basis-64 jika isi asli bersifat biner. Amazon Data Firehose tidak mengubah dan/atau menyandikan nilai yang dikonfigurasi dan menggunakan konten apa adanya.

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 JSON objek 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": ""
  }
                    

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

Tubuh membawa satu JSON dokumen dengan JSON Skema berikut (ditulis dalamYAML):

"$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="
    }
  ]
}
                    

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

Kode HTTP status MUST berada dalam kisaran 2XX, 4XX atau 5XX.

Server Amazon Data Firehose NOT mengikuti pengalihan (kode status 3XX). Hanya kode respons 200 yang dianggap sebagai pengiriman catatan yang berhasil ke 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.

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

Content-Encoding digunakan MUSTNOT. Tubuh tidak MUST terkompresi.

Header Content-Length MUST hadir jika respons memiliki tubuh.

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
}
                    

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 HTTP akhir. 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.