Idempotensi
Jaringan bisa gagal di saat paling kritis: Anda POST sebuah pengiriman, koneksi terputus, dan sekarang Anda tidak tahu apakah email tersebut terkirim atau tidak. Idempotensi memungkinkan Anda mencoba lagi permintaan tersebut dengan aman. Kirim header Idempotency-Key yang sama lagi dan Bird akan membalas respons asli alih-alih memproses permintaan untuk kedua kalinya.
Cara kerja
Idempotensi bersifat opt-in. Tambahkan header Idempotency-Key pada permintaan POST, PATCH, PUT, atau DELETE yang didukung. Permintaan tanpa header ini diproses seperti biasa tanpa deduplikasi. Permintaan GET mengabaikan header ini.
Pada API pelanggan, mutasi bercakupan workspace dan organisasi mendukung pemutaran ulang respons yang dijelaskan di bawah. Operasi khusus pengguna, operasi tanpa cakupan yang tidak terautentikasi, dan stream mengabaikannya. Operasi dengan kontrak pemutaran ulang terpisah mendefinisikan perilakunya di halaman referensi masing-masing. Sebagai contoh, Membuat panggilan suara menyimpan snapshot penerimaan asli untuk percobaan ulang yang cocok saat Anda menyertakan kunci.
SDK menghasilkan kunci untuk setiap pemanggilan yang mengubah data dan menggunakannya kembali untuk percobaan ulang otomatis, termasuk pembuatan panggilan. Anda tidak perlu menyertakan kunci sendiri untuk percobaan ulang SDK otomatis. Sertakan kunci Anda sendiri jika satu operasi yang dimaksud mencakup beberapa pemanggilan SDK terpisah, misalnya percobaan ulang setelah aplikasi Anda di-restart. Contoh-contoh berikut menunjukkan kasus tersebut.
await bird.email.send(
{
from: "hello@yourdomain.com",
to: ["delivered@messagebird.dev"],
subject: "Welcome!",
html: "<p>Thanks for signing up.</p>",
},
{ idempotencyKey: "welcome-user/usr_abc123" },
);client.email.send(
from_="hello@yourdomain.com",
to=["delivered@messagebird.dev"],
subject="Welcome!",
html="<p>Thanks for signing up.</p>",
options={"idempotency_key": "welcome-user/usr_abc123"},
)_, err := client.Email.Send(context.Background(), bird.EmailSendParams{
From: "hello@yourdomain.com",
To: []string{"delivered@messagebird.dev"},
Subject: "Welcome!",
HTML: "<p>Thanks for signing up.</p>",
}, option.WithIdempotencyKey("welcome-user/usr_abc123"))$bird->email->send(
from: 'hello@yourdomain.com',
to: ['delivered@messagebird.dev'],
subject: 'Welcome!',
html: '<p>Thanks for signing up.</p>',
options: new RequestOptions(idempotencyKey: 'welcome-user/usr_abc123'),
);curl -X POST https://us1.platform.bird.com/v1/email/messages \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: welcome-user/usr_abc123" \
-d '{
"from": "hello@yourdomain.com",
"to": ["delivered@messagebird.dev"],
"subject": "Welcome!",
"html": "<p>Thanks for signing up.</p>"
}'Kunci adalah string tidak kosong dengan panjang hingga 255 karakter. Nilai header kosong melewati deduplikasi. Format yang direkomendasikan adalah kunci deterministik yang diturunkan dari entitas Anda sendiri, <event-type>/<entity-id> (misalnya welcome-user/usr_abc123), sehingga percobaan ulang lintas restart proses menggunakan kunci yang sama; UUID acak per operasi logis juga bisa digunakan. SDK Bird menghasilkan kunci UUID secara otomatis untuk setiap permintaan yang mengubah data dan menggunakannya kembali di seluruh percobaan ulang internalnya.
Kunci dicakupkan ke workspace Anda, atau ke organisasi Anda pada endpoint tingkat organisasi. Respons yang sudah selesai disimpan selama 3 jam; percobaan ulang setelah jendela waktu tersebut diproses sebagai permintaan baru. Jendela waktu ini mencakup jadwal coba lagi yang umum. Tidak ada catatan deduplikasi yang tersisa setelah kedaluwarsa.
Replay
Saat Bird melihat kunci yang sudah diselesaikan, ia mengembalikan respons yang di-cache, kode status sama, body sama, tanpa menjalankan ulang permintaan. Respons yang di-replay membawa satu header tambahan agar Anda dapat membedakannya dari pemrosesan baru:
Contoh kode
HTTP/1.1 202 Accepted
Idempotency-Replay: trueRespons yang dipertahankan dapat mencakup penolakan 4xx. Gunakan kunci baru saat memperbaiki permintaan: jika penolakannya dipertahankan, percobaan ulang tanpa perubahan akan memutar ulang penolakan tersebut, dan permintaan yang diubah mengembalikan 409 E01005 IdempotencyKeyReuse. Respons 5xx tidak dipertahankan, jadi coba lagi dengan kunci dan permintaan yang sama.
Mode kegagalan
| Skenario | Respons |
|---|---|
| Kunci sama, permintaan sama, permintaan awal selesai | Respons yang di-cache diputar ulang dengan Idempotency-Replay: true |
| Kunci sama, body permintaan atau endpoint berbeda | 409, E01005 IdempotencyKeyReuse |
| Kunci sama, permintaan awal masih dalam proses | 409, E01004 RequestInProgress |
| Kunci lebih dari 255 karakter pada endpoint yang mendeklarasikan header | 422, E01001 ValidationError |
| Perlindungan idempotensi tidak tersedia sebelum eksekusi | 503, E01033 IdempotencyUnavailable; percobaan ini tidak dieksekusi |
Menggunakan kembali kunci yang sudah selesai dengan permintaan berbeda dianggap sebagai bug di sisi klien: Bird langsung mengembalikan 409 alih-alih diam-diam memberikan respons yang tidak sesuai dengan yang Anda kirim. Buat kunci baru untuk permintaan baru. Perbandingan mencakup method, endpoint, path dan query parameter, serta raw request body, termasuk spasi JSON. Upload multipart membandingkan nama bagian, nama file, dan konten; boundary dan urutan bagian tidak memengaruhi pemutaran ulang.
RequestInProgress berarti permintaan yang berjalan bersamaan dengan kunci yang sama belum selesai, biasanya karena timeout sisi klien yang agresif mencoba ulang sementara percobaan pertama masih diproses. Kunci in-flight kedaluwarsa dalam 30 detik, jadi tunggu sebentar dan coba lagi. Lihat Errors untuk format respons kesalahan yang membungkusnya.
Apa yang tidak di-cache
Respons 5xx tidak pernah di-cache. Kunci dibuka dan Bird dapat memproses percobaan ulang sebagai percobaan baru. Coba lagi respons 5xx dan timeout dengan backoff menggunakan kunci dan permintaan yang sama. Sebuah operasi bisa berlaku sebelum responsnya disimpan; jika respons tersebut hilang, atau kunci in-flight kedaluwarsa, percobaan ulang dapat mengeksekusi operasi tersebut lagi.
Jika perlindungan idempotensi tidak tersedia sebelum eksekusi, API mengembalikan 503 E01033 IdempotencyUnavailable tanpa mengeksekusi percobaan ini. Pertahankan kunci pada setiap percobaan ulang. Error ini tidak menjelaskan hasil dari percobaan sebelumnya dengan kunci yang sama.
Panduan praktis
- Buat satu kunci per operasi logis dan gunakan kembali untuk setiap percobaan HTTP dari operasi tersebut.
- Coba lagi saat error jaringan, timeout, dan 5xx dengan exponential backoff, menggunakan kembali kunci yang sama setiap kali.
- Perlakukan 409 IdempotencyKeyReuse sebagai bug dalam pembuatan kunci Anda. Jangan coba lagi.
- Kunci bersifat opsional pada mutasi. Gunakan kunci saat Anda membutuhkan perlindungan percobaan ulang; abaikan pada permintaan GET.
Langkah selanjutnya
- Referensi idempotensi API: skema header dan response-header
- Konsep SDK: pembuatan kunci otomatis dan perilaku coba lagi di SDK
- Errors: respons kesalahan dan katalog kode
- Mengirim email: endpoint send dan batch
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.