आइडेम्पोटेंसी

नेटवर्क सबसे बुरे समय पर विफल होते हैं: आप भेजने के लिए POST करते हैं, कनेक्शन टूट जाता है, और अब आपको पता नहीं कि ईमेल गया या नहीं। आइडेम्पोटेंसी से आप उस अनुरोध के लिए सुरक्षित रूप से फिर से प्रयास कर सकते हैं। वही Idempotency-Key हेडर दोबारा भेजें, तो Bird अनुरोध को दूसरी बार प्रोसेस करने के बजाय मूल प्रतिक्रिया को दोहराता है।

यह कैसे काम करता है

आइडेम्पोटेंसी वैकल्पिक है। समर्थित 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 कुंजी बनाते हैं और अपने आंतरिक फिर से प्रयासों में उसी का दोबारा उपयोग करते हैं।

कुंजियों का दायरा आपका वर्कस्पेस होता है, या संगठन-स्तर के एंडपॉइंट पर आपका संगठन। पूरी हुई प्रतिक्रिया 3 घंटे तक रखी जाती है; इस अवधि के बाद फिर से प्रयास करने पर अनुरोध नए अनुरोध की तरह प्रोसेस होता है। यह अवधि सामान्य फिर से प्रयास के शेड्यूल को कवर करती है। अवधि समाप्त होने के बाद डुप्लिकेट-हटाव का कोई रिकॉर्ड नहीं रहता।

रीप्ले

जब Bird को ऐसी कुंजी मिलती है जिसे वह पहले पूरा कर चुका है, तो वह अनुरोध को दोबारा चलाए बिना कैश की गई प्रतिक्रिया लौटाता है, उसी स्टेटस कोड और उसी बॉडी के साथ। दोहराई गई प्रतिक्रियाओं में एक अतिरिक्त हेडर होता है, ताकि आप उन्हें नई प्रोसेसिंग से अलग पहचान सकें:

HTTP/1.1 202 Accepted
Idempotency-Replay: true

रखी गई प्रतिक्रियाओं में 4xx अस्वीकृतियाँ भी शामिल हो सकती हैं। किसी अनुरोध को सुधारते समय नई कुंजी का उपयोग करें: अगर उसकी अस्वीकृति रखी गई थी, तो बिना बदलाव वाला फिर से प्रयास उसी अस्वीकृति को दोहराता है, और बदला हुआ अनुरोध 409 E01005 IdempotencyKeyReuse लौटाता है। 5xx प्रतिक्रियाएँ रखी नहीं जातीं, इसलिए उनके लिए उसी कुंजी और उसी अनुरोध के साथ फिर से प्रयास करें।

विफलता की स्थितियाँ

किसी पूरी हो चुकी कुंजी को अलग अनुरोध के साथ दोबारा इस्तेमाल करना क्लाइंट की बग माना जाता है: Bird आपको चुपचाप ऐसी प्रतिक्रिया देने के बजाय, जो आपके भेजे अनुरोध से मेल नहीं खाती, तुरंत 409 लौटाता है। नए अनुरोध के लिए नई कुंजी बनाएँ। तुलना में मेथड, एंडपॉइंट, पाथ और क्वेरी पैरामीटर, और कच्ची अनुरोध बॉडी शामिल होती है, जिसमें JSON व्हाइटस्पेस भी शामिल है। मल्टीपार्ट अपलोड में पार्ट के नाम, फ़ाइलनाम और सामग्री की तुलना होती है; बाउंड्री और पार्ट का क्रम रीप्ले को प्रभावित नहीं करते।

RequestInProgress का अर्थ है कि उसी कुंजी वाला एक समवर्ती अनुरोध अभी पूरा नहीं हुआ है। आमतौर पर ऐसा तब होता है जब क्लाइंट की ओर का बहुत छोटा टाइमआउट पहले प्रयास के प्रोसेस होते समय ही फिर से प्रयास करता है। प्रगति में चल रहे अनुरोध का लॉक 30 सेकंड के भीतर समाप्त हो जाता है, इसलिए थोड़ी देर रुककर फिर से प्रयास करें। ये त्रुटियाँ जिस त्रुटि प्रतिक्रिया में लिपटी आती हैं, उसके लिए त्रुटियाँ देखें।

क्या कैश नहीं होता

5xx प्रतिक्रियाएँ कभी कैश नहीं होतीं। कुंजी अनलॉक हो जाती है और Bird फिर से प्रयास को नए प्रयास की तरह प्रोसेस कर सकता है। 5xx प्रतिक्रियाओं और टाइमआउट पर उसी कुंजी और अनुरोध के साथ बैकऑफ़ के साथ फिर से प्रयास करें। कोई ऑपरेशन अपनी प्रतिक्रिया सहेजे जाने से पहले ही प्रभावी हो सकता है; अगर वह प्रतिक्रिया खो जाती है, या प्रगति में चल रहे अनुरोध का लॉक समाप्त हो जाता है, तो फिर से प्रयास करने पर ऑपरेशन दोबारा निष्पादित हो सकता है।

अगर निष्पादन से पहले आइडेम्पोटेंसी सुरक्षा उपलब्ध नहीं है, तो API इस प्रयास को निष्पादित किए बिना 503 E01033 IdempotencyUnavailable लौटाता है। हर फिर से प्रयास में वही कुंजी रखें। यह त्रुटि उसी कुंजी वाले किसी पिछले प्रयास का परिणाम नहीं बताती।

व्यावहारिक मार्गदर्शन

• हर तार्किक ऑपरेशन के लिए एक कुंजी बनाएँ और उस ऑपरेशन के हर HTTP प्रयास में उसी का दोबारा इस्तेमाल करें।
• नेटवर्क त्रुटियों, टाइमआउट और 5xx पर एक्सपोनेंशियल बैकऑफ़ के साथ फिर से प्रयास करें, और हर बार वही कुंजी दोबारा इस्तेमाल करें।
• 409 IdempotencyKeyReuse को अपनी कुंजी बनाने की प्रक्रिया में बग मानें। इस पर फिर से प्रयास न करें।
• म्यूटेशन पर कुंजियाँ वैकल्पिक हैं। जब आपको फिर से प्रयास के लिए सुरक्षा चाहिए, तब एक कुंजी इस्तेमाल करें; GET अनुरोधों पर इसे छोड़ दें।

अगले कदम

• Idempotency API संदर्भ: हेडर और प्रतिक्रिया-हेडर स्कीमा
• SDK अवधारणाएँ: SDK में स्वचालित कुंजी निर्माण और फिर से प्रयास करने का व्यवहार
• त्रुटियाँ: त्रुटि प्रतिक्रिया और कोड सूची
• ईमेल भेजना: भेजने और बैच एंडपॉइंट