Idempotency
नेटवर्क सबसे गलत समय पर विफल होते हैं: आप एक send POST करते हैं, कनेक्शन टूट जाता है, और अब आपको नहीं पता कि ईमेल गया या नहीं। Idempotency आपको वह अनुरोध सुरक्षित रूप से फिर से भेजने देती है। वही Idempotency-Key हेडर दोबारा भेजें और Bird अनुरोध को दूसरी बार प्रोसेस करने के बजाय मूल प्रतिक्रिया रीप्ले कर देता है।
यह कैसे काम करता है
Idempotency ऑप्ट-इन है। किसी समर्थित POST, PATCH, PUT, या DELETE अनुरोध में Idempotency-Key हेडर जोड़ें। इसके बिना अनुरोध सामान्य रूप से प्रोसेस होते हैं, कोई डिडुप्लिकेशन नहीं होता। GET अनुरोध इस हेडर को अनदेखा करते हैं।
कस्टमर API पर, वर्कस्पेस- और ऑर्गनाइज़ेशन-स्कोप्ड म्यूटेशन नीचे वर्णित रिस्पॉन्स रीप्ले का समर्थन करते हैं। केवल-यूज़र और अनस्कोप्ड अनऑथेंटिकेटेड ऑपरेशन और स्ट्रीम इसे बायपास करते हैं। अलग रीप्ले कॉन्ट्रैक्ट वाले ऑपरेशन अपना व्यवहार अपने रेफ़रेंस पेज में परिभाषित करते हैं। उदाहरण के लिए, वॉइस कॉल बनाएँ कुंजी देने पर मिलान करने वाली पुनः प्रयासों के लिए मूल स्वीकृति स्नैपशॉट बनाए रखता है।
SDK हर म्यूटेटिंग कॉल के लिए एक कुंजी जनरेट करते हैं और स्वचालित पुनः प्रयासों में उसे दोबारा उपयोग करते हैं, जिसमें कॉल क्रिएशन भी शामिल है। स्वचालित SDK पुनः प्रयासों के लिए आपको कोई कुंजी देने की ज़रूरत नहीं है। अपनी खुद की कुंजी तब दें जब एक इच्छित ऑपरेशन अलग-अलग SDK कॉल में फैला हो, जैसे कि अपना एप्लिकेशन रीस्टार्ट करने के बाद फिर से प्रयास करना। ये उदाहरण उसी स्थिति को दर्शाते हैं।
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>"
}'कुंजी 255 अक्षरों तक की कोई भी नॉन-एम्प्टी स्ट्रिंग हो सकती है। खाली हेडर वैल्यू डिडुप्लिकेशन को छोड़ देती है। अनुशंसित फ़ॉर्मेट आपकी अपनी एंटिटी से प्राप्त एक डिटर्मिनिस्टिक कुंजी है, <event-type>/<entity-id> (उदाहरण के लिए welcome-user/usr_abc123), ताकि प्रोसेस रीस्टार्ट के बाद भी पुनः प्रयास एक ही कुंजी साझा करें; प्रति लॉजिकल ऑपरेशन एक रैंडम UUID भी काम करता है। Bird SDK हर म्यूटेटिंग अनुरोध के लिए स्वचालित रूप से एक UUID कुंजी जनरेट करते हैं और अपने आंतरिक पुनः प्रयासों में उसे दोबारा उपयोग करते हैं।
Keys आपके वर्कस्पेस में scoped होती हैं, या organization-level endpoints पर आपके organization में। एक पूर्ण प्रतिक्रिया 3 घंटे तक रखी जाती है; उस विंडो के बाद फिर से प्रयास एक नए अनुरोध के रूप में प्रोसेस होता है। यह विंडो सामान्य retry शेड्यूल को कवर करती है। इसके समाप्त होने के बाद कोई deduplication रिकॉर्ड शेष नहीं रहता।
रीप्ले
जब Bird को कोई ऐसी key दिखती है जो पहले पूरी हो चुकी है, तो यह कैश की गई प्रतिक्रिया लौटाता है, वही स्टेटस कोड, वही बॉडी, अनुरोध को दोबारा चलाए बिना। रीप्ले की गई प्रतिक्रियाओं में एक अतिरिक्त हेडर होता है ताकि आप उन्हें ताज़ा प्रोसेसिंग से अलग पहचान सकें:
कोड उदाहरण
HTTP/1.1 202 Accepted
Idempotency-Replay: trueरिटेन किए गए रिस्पॉन्स में 4xx रिजेक्शन शामिल हो सकते हैं। रिक्वेस्ट सुधारते समय नई कुंजी का उपयोग करें: यदि उसका रिजेक्शन रिटेन किया गया था, तो अपरिवर्तित रीट्राई उसे रीप्ले करेगी, और बदली हुई रिक्वेस्ट 409 E01005 IdempotencyKeyReuse लौटाएगी। 5xx रिस्पॉन्स रिटेन नहीं किए जाते, इसलिए उन्हें उसी कुंजी और रिक्वेस्ट के साथ फिर से प्रयास करें।
विफलता स्थितियाँ
| परिदृश्य | प्रतिक्रिया |
|---|---|
| समान कुंजी, समान रिक्वेस्ट, मूल पूर्ण हो चुकी | Idempotency-Replay: true के साथ कैश की गई प्रतिक्रिया रीप्ले |
| समान कुंजी, भिन्न रिक्वेस्ट बॉडी या एंडपॉइंट | 409, E01005 IdempotencyKeyReuse |
| समान कुंजी, मूल रिक्वेस्ट अभी फ़्लाइट में | 409, E01004 RequestInProgress |
| हेडर डिक्लेयर करने वाले एंडपॉइंट पर 255 अक्षरों से लंबी कुंजी | 422, E01001 ValidationError |
| निष्पादन से पहले इडेम्पोटेंसी सुरक्षा अनुपलब्ध | 503, E01033 IdempotencyUnavailable; यह प्रयास execute नहीं होता |
पूर्ण हो चुकी कुंजी को भिन्न रिक्वेस्ट के साथ दोबारा उपयोग करना क्लाइंट बग माना जाता है: Bird आपको चुपचाप ऐसा रिस्पॉन्स सौंपने के बजाय तुरंत 409 लौटाता है जो आपकी भेजी गई रिक्वेस्ट से मेल नहीं खाता। नई रिक्वेस्ट के लिए नई कुंजी जनरेट करें। तुलना में मेथड, एंडपॉइंट, पाथ और क्वेरी पैरामीटर, तथा रॉ रिक्वेस्ट बॉडी शामिल होती है, जिसमें JSON व्हाइटस्पेस भी शामिल है। मल्टीपार्ट अपलोड में पार्ट नाम, फ़ाइलनाम और कंटेंट की तुलना होती है; बाउंड्रीज़ और पार्ट क्रम रीप्ले को प्रभावित नहीं करते।
RequestInProgress का मतलब है कि उसी key वाला एक समवर्ती अनुरोध अभी पूरा नहीं हुआ है, आमतौर पर यह तब होता है जब aggressive client-side timeout पहले प्रयास के प्रोसेस होने के दौरान ही फिर से प्रयास करता है। In-flight lock 30 सेकंड के भीतर समाप्त हो जाता है, इसलिए थोड़ा रुकें और फिर से प्रयास करें। इनके साथ आने वाले envelope के लिए त्रुटियाँ देखें।
क्या कैश नहीं होता
5xx प्रतिक्रियाएँ कभी कैश नहीं होतीं। Key अनलॉक हो जाती है और Bird फिर से प्रयास को एक नए प्रयास के रूप में प्रोसेस कर सकता है। 5xx प्रतिक्रियाओं और timeouts को उसी key और अनुरोध के साथ backoff लगाकर फिर से प्रयास करें। एक ऑपरेशन अपनी प्रतिक्रिया retain होने से पहले प्रभावी हो सकता है; यदि वह प्रतिक्रिया खो जाती है, या in-flight lock समाप्त हो जाता है, तो फिर से प्रयास ऑपरेशन को दोबारा execute कर सकता है।
यदि execution से पहले idempotency सुरक्षा अनुपलब्ध है, तो API इस प्रयास को execute किए बिना 503 E01033 IdempotencyUnavailable लौटाता है। हर फिर से प्रयास पर key बनाए रखें। यह त्रुटि उसी key के साथ पहले के किसी प्रयास के परिणाम का वर्णन नहीं करती।
व्यावहारिक मार्गदर्शन
- हर logical ऑपरेशन के लिए एक key बनाएँ और उस ऑपरेशन के हर HTTP प्रयास में उसे दोबारा उपयोग करें।
- नेटवर्क त्रुटियों, timeouts, और 5xx पर exponential backoff के साथ फिर से प्रयास करें, हर बार वही key दोबारा उपयोग करें।
- 409 IdempotencyKeyReuse को अपनी key generation में bug मानें। इसे फिर से प्रयास न करें।
- म्यूटेशन पर कुंजी वैकल्पिक है। जब आपको फिर से प्रयास करने की सुरक्षा चाहिए तब इसका उपयोग करें; GET अनुरोधों पर इसे छोड़ दें।
अगले कदम
- Idempotency API संदर्भ: हेडर और response-header schemas
- SDK concepts: SDKs में स्वचालित key generation और retry व्यवहार
- त्रुटियाँ: त्रुटि प्रतिक्रिया envelope और code catalog
- ईमेल भेजना: send और batch endpoints
संबंधित संसाधन
इस विषय के लिए डॉक्यूमेंटेशन, गाइड और उदाहरणों के साथ आगे बढ़ें। संसाधन अंग्रेज़ी में हैं।