فنی · پاسخ مستند
کلید idempotency چیست؟ جلوگیری از ارسال تکراری ایمیل
کلید idempotency مقداری یکتاست که کلاینت تولید میکند و در درخواست API می‌فرستد تا تضمین شود عملیات دقیقاً یک بار اجرا میشود. اگر درخواست با همان کلید دوباره ارسال شود، سرور تکراری بودن آن را تشخیص میدهد و بدون پردازش دوباره، پاسخ اصلی را برمی‌گرداند.
سازوکار عملکرد
وقتی کلاینت درخواستی با کلید idempotency می‌فرستد، سرور کلید و پاسخ حاصل را در یک cache ذخیره میکند. اگر درخواست بعدی با همان کلید برسد، سرور منطق اجرا را کنار می‌گذارد و صرفاً پاسخ ذخیره‌شده را برمی‌گرداند. این سازوکار برای سیستمهای توزیعشده حیاتی است، جایی که timeoutهای شبکه ممکن است کلاینت را در این ابهام بگذارند که آیا درخواست به سرور رسیده است یا نه.
اهمیت برای فرستندگان
در ایمیل تراکنشی، ارسال دوباره یک پیام می‌تواند تجربه کاربری بدی ایجاد کند و گزارش‌های اسپم را افزایش دهد. کلیدهای idempotency به توسعه‌دهندگان امکان می‌دهند برای فراخوانی‌های ناموفق شبکه منطق تلاش مجدد تهاجمی پیاده کنند، بدون اینکه خطر ارسال ایمیل تکراری به گیرنده وجود داشته باشد. این کار قابلیت اطمینان و سازگاری را در سراسر خط لوله تحویل تضمین میکند.
ملاحظات عملیاتی
کلیدها باید با UUID یا یک رشته تصادفی با آنتروپی بالا تولید شوند تا تداخل پیش نیاید. سرورها معمولاً این کلیدها را پس از 24 ساعت منقضی می‌کنند. توسعه‌دهندگان باید مطمئن شوند کلید به هدف مشخص همان پیام گره خورده است؛ تغییر بدنه ایمیل یا گیرنده با حفظ همان کلید باید به خطا منجر شود، نه به پاسخ موفق ذخیره‌شده.
نمونه پیاده‌سازی
یک برنامه SaaS برای ایمیل بازنشانی رمز عبور یک کلید یکتا تولید میکند. برنامه API ایمیل را فراخوانی میکند اما اتصال پیش از دریافت پاسخ قطع میشود. برنامه درخواست را با همان کلید دوباره ارسال میکند. API می‌بیند که کلید از قبل وجود دارد و بدون ارسال ایمیل دوم به کاربر، 200 OK برمی‌گرداند. ابزارهای رایگان SendHQ به توسعه‌دهندگان کمک می‌کنند زیرساخت ایمیل خود را به‌طور کارآمد مدیریت کنند.
مدیریت خطا
اگر درخواستی تغییر کند اما با یک کلید idempotency موجود ارسال شود، سرور باید خطای conflict برگرداند. این کار از استفاده دوباره تصادفی از کلیدها برای پیام‌های مختلف جلوگیری میکند. مدیریت درست شامل گرفتن این conflictها و تولید کلید جدید برای payload به‌روزشده درخواست است.
پرسش‌هایی که تیم‌ها می‌پرسند
آیا کلید idempotency همان Message ID است؟
خیر. Message ID را سرور پس از پردازش اختصاص میدهد، در حالی که کلید idempotency را کلاینت پیش از ارسال درخواست تعیین میکند.
اگر کلید idempotency منقضی شود چه میشود؟
اگر کلید از cache سرور منقضی شود، تلاش مجدد بهعنوان درخواست جدید در نظر گرفته میشود که ممکن است به ارسال ایمیل تکراری منجر شود.
بهترین نوع داده برای کلیدهای idempotency چیست؟
UUID v4 استاندارد صنعت است، چون احتمال تداخل آن در سیستمهای توزیعشده ناچیز است.
منابع اصلی
- مستندات SendGrid — Twilio SendGrid
- مستندات توسعه‌دهندگان Postmark — Postmark