Idempotency-Key हेडर
किसी अनुरोध को डुप्लिकेट ऑपरेशन बनाए बिना फिर से प्रयास करने के लिए Idempotency-Key का उपयोग करें। गारंटी ठीक एक बार स्वीकृति की है: 3 घंटे की रिटेंशन अवधि के भीतर, उसी कुंजी और समान अनुरोध वाले फिर से प्रयास मूल ऑपरेशन पर ही पहुँचते हैं, भले ही उसकी प्रतिक्रिया आपसे खो गई हो। फिर से प्रयास की रणनीति के लिए आइडेम्पोटेंसी देखें।
अनुरोध हेडर
| हेडर | शर्तें |
|---|---|
Idempotency-Key | वैकल्पिक। 255 वर्णों तक की कोई भी गैर-खाली स्ट्रिंग; UUID v4 की सलाह दी जाती है। समर्थित POST, PATCH, PUT और DELETE ऑपरेशनों पर लागू होता है; GET, HEAD और OPTIONS पर अनदेखा किया जाता है। |
वर्कस्पेस और संगठन के दायरे वाले म्यूटेशन नीचे बताए गए प्रतिक्रिया रीप्ले का समर्थन करते हैं। केवल-उपयोगकर्ता वाले ऑपरेशन, बिना दायरे वाले अप्रमाणित ऑपरेशन और स्ट्रीम इसे लागू नहीं करते। जिन ऑपरेशनों का अलग रीप्ले कॉन्ट्रैक्ट है, उनका व्यवहार उनके रेफ़रेंस पेज पर बताया गया है।
अगर आप हेडर नहीं भेजते या खाली मान भेजते हैं, तो अनुरोध बिना डीडुप्लिकेशन के सामान्य रूप से प्रोसेस होता है। जो एंडपॉइंट यह हेडर घोषित करते हैं, उन पर 255 वर्णों से लंबी कुंजी भेजने पर 422 और कोड E01001 ValidationError लौटता है।
कुंजियाँ आपके वर्कस्पेस के दायरे में होती हैं, या संगठन-स्तर के एंडपॉइंट पर आपके संगठन के दायरे में, और लगभग 3 घंटे तक रखी जाती हैं। यह अवधि बीतने के बाद दोबारा इस्तेमाल की गई कुंजी वाला अनुरोध नए अनुरोध की तरह प्रोसेस होता है।
प्रतिक्रिया का व्यवहार
| स्थिति | प्रतिक्रिया |
|---|---|
| किसी कुंजी के साथ पहला अनुरोध | सामान्य रूप से प्रोसेस होता है; पूरी हुई प्रतिक्रिया को रीप्ले के लिए रखा जा सकता है; 5xx प्रतिक्रियाएँ नहीं रखी जातीं। |
| वही कुंजी, रिटेंशन अवधि के भीतर समान अनुरोध | मूल ऑपरेशन; सहेजी गई प्रतिक्रिया Idempotency-Replay: true के साथ रीप्ले होती है। |
| वही कुंजी, अलग अनुरोध | E01005 IdempotencyKeyReuse के साथ 409। नए अनुरोध के लिए नई कुंजी बनाएँ। |
| वही कुंजी, मूल अनुरोध अभी भी प्रोसेस हो रहा है | E01004 RequestInProgress के साथ 409। प्रतीक्षा करें और उसी कुंजी और समान अनुरोध के साथ फिर से प्रयास करें। |
मूल अनुरोध ने 5xx लौटाया | त्रुटि प्रतिक्रिया नहीं सहेजी जाती। उसी कुंजी और समान अनुरोध के साथ फिर से प्रयास करें। |
| निष्पादन से पहले आइडेम्पोटेंसी सुरक्षा उपलब्ध नहीं | 503 के साथ E01033 IdempotencyUnavailable। यह प्रयास निष्पादित नहीं होता; उसी कुंजी और उसी अनुरोध के साथ फिर से प्रयास करें। |
दोबारा चलाई गई प्रतिक्रिया बाइट-दर-बाइट मूल प्रतिक्रिया जैसी होती है (वही स्टेटस कोड, वही बॉडी)। उसे केवल अतिरिक्त हेडर से पहचाना जा सकता है:
HTTP/1.1 202 Accepted
Idempotency-Replay: true"Identical request" में मेथड, एंडपॉइंट, पाथ और क्वेरी पैरामीटर, और कच्ची अनुरोध बॉडी शामिल हैं; इन मानों में कोई भी अंतर, JSON व्हाइटस्पेस सहित, E01005 लौटाता है। मल्टीपार्ट अपलोड में पार्ट के नाम, फ़ाइलनाम और सामग्री की तुलना होती है; बाउंड्री और पार्ट के क्रम का रीप्ले पर कोई असर नहीं पड़ता। दोनों 409 त्रुटियाँ मानक त्रुटि प्रतिक्रिया में लिपटी आती हैं।
सहेजी गई प्रतिक्रियाओं में 4xx अस्वीकृतियाँ भी हो सकती हैं। अनुरोध सुधारते समय नई कुंजी का उपयोग करें: अगर उसकी अस्वीकृति सहेजी गई थी, तो बिना बदलाव का फिर से प्रयास उसी अस्वीकृति को दोबारा लौटाता है, और बदला हुआ अनुरोध 409 E01005 IdempotencyKeyReuse लौटाता है।
टाइमआउट या 5xx मिलने पर तीन घंटे के भीतर उसी कुंजी और समान अनुरोध के साथ सीमित बैकऑफ़ से फिर से प्रयास करें। मूल प्रतिक्रिया खो जाने पर भी ठीक एक बार स्वीकृति की गारंटी लागू रहती है। E01033 IdempotencyUnavailable का मतलब है कि यह प्रयास निष्पादित नहीं हुआ; यह किसी पिछले प्रयास का परिणाम नहीं बताता। हर फिर से प्रयास में वही कुंजी रखें।
संदेश भेजने के लिए, ठीक एक बार स्वीकृति का मतलब है कि मेल खाने वाले सभी फिर से प्रयासों में केवल एक भेजना स्वीकार होता है। डिलीवरी की पुष्टि के लिए संदेश की स्थिति देखें। तीन घंटे के बाद दोबारा भेजने से पहले मूल ऑपरेशन का परिणाम जाँचें, क्योंकि समाप्त हो चुकी कुंजी या नई कुंजी एक और ऑपरेशन बना सकती है।
SDK का व्यवहार
आधिकारिक SDK हर बदलाव करने वाले अनुरोध के साथ अपने-आप बनी UUID Idempotency-Key जोड़ते हैं। यह हर तार्किक कॉल के लिए एक बार बनती है और उस कॉल के सभी फिर से प्रयासों में दोबारा इस्तेमाल होती है। जब एक तार्किक ऑपरेशन कई SDK कॉल में फैला हो, तो आप हर कॉल के लिए अपनी कुंजी दे सकते हैं (TypeScript में idempotencyKey, Go में option.WithIdempotencyKey, Python में idempotency_key, PHP में new RequestOptions(idempotencyKey: ...))। रीप्ले पहचानने के लिए, हर SDK के ट्रांसपोर्ट-मेटाडेटा एक्सेसर से Idempotency-Replay प्रतिक्रिया हेडर पढ़ें: TypeScript में .withResponse(), Go में option.WithResponseInto और Python में with_raw_response।
संबंधित
- आइडेम्पोटेंसी की अवधारणाएँ: फिर से प्रयास की रणनीति, कुंजी का डिज़ाइन और रीप्ले की सीमाएँ
- त्रुटि प्रतिक्रियाएँ:
E01004औरE01005को समेटने वाली त्रुटि प्रतिक्रिया - ईमेल संदेश: भेजने वाला एंडपॉइंट, जहाँ कुंजी का सबसे अधिक उपयोग होता है
- SDK की अवधारणाएँ: स्वचालित कुंजी निर्माण और फिर से प्रयास
संबंधित संसाधन
इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।