Idempotency-Key हेडर
Bird API में Idempotency-Key हेडर के ज़रिए वैकल्पिक अनुरोध डीडुप्लिकेशन उपलब्ध है। यह पेज वायर कॉन्ट्रैक्ट बताता है। फिर से प्रयास की रणनीति के लिए Idempotency देखें।
अनुरोध हेडर
| हेडर | शर्तें |
|---|---|
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। लॉक लगभग 30 सेकंड में समाप्त हो जाता है; प्रतीक्षा करें और फिर से प्रयास करें। |
मूल अनुरोध ने 5xx लौटाया | कैश नहीं किया जाता: कुंजी अनलॉक हो जाती है और फिर से प्रयास को नए अनुरोध की तरह प्रोसेस किया जाता है। |
| निष्पादन से पहले आइडेम्पोटेंसी सुरक्षा उपलब्ध नहीं | 503 के साथ E01033 IdempotencyUnavailable। यह प्रयास निष्पादित नहीं होता; उसी कुंजी और उसी अनुरोध के साथ फिर से प्रयास करें। |
दोबारा चलाई गई प्रतिक्रिया बाइट-दर-बाइट मूल प्रतिक्रिया जैसी होती है (वही स्टेटस कोड, वही बॉडी)। उसे केवल अतिरिक्त हेडर से पहचाना जा सकता है:
HTTP/1.1 202 Accepted
Idempotency-Replay: true"Identical request" में मेथड, एंडपॉइंट, पाथ और क्वेरी पैरामीटर, और कच्ची अनुरोध बॉडी शामिल हैं; इन मानों में कोई भी अंतर, JSON व्हाइटस्पेस सहित, E01005 लौटाता है। मल्टीपार्ट अपलोड में पार्ट के नाम, फ़ाइलनाम और सामग्री की तुलना होती है; बाउंड्री और पार्ट के क्रम का रीप्ले पर कोई असर नहीं पड़ता। दोनों 409 त्रुटियाँ मानक त्रुटि प्रतिक्रिया में लिपटी आती हैं।
सहेजी गई प्रतिक्रियाओं में 4xx अस्वीकृतियाँ भी हो सकती हैं। अनुरोध सुधारते समय नई कुंजी का उपयोग करें: अगर उसकी अस्वीकृति सहेजी गई थी, तो बिना बदलाव का फिर से प्रयास उसी अस्वीकृति को दोबारा लौटाता है, और बदला हुआ अनुरोध 409 E01005 IdempotencyKeyReuse लौटाता है।
5xx प्रतिक्रियाएँ कभी कैश नहीं की जातीं। बैकऑफ़ के साथ उसी कुंजी और अनुरोध से फिर से प्रयास करें। E01033 IdempotencyUnavailable का मतलब है कि यह प्रयास निष्पादित नहीं हुआ; यह किसी पिछले प्रयास का परिणाम नहीं बताता। हर फिर से प्रयास में वही कुंजी रखें।
कोई ऑपरेशन अपनी प्रतिक्रिया सहेजे जाने से पहले ही प्रभावी हो सकता है। अगर वह प्रतिक्रिया खो जाए, या चालू अनुरोध का लॉक समाप्त हो जाए, तो फिर से प्रयास करने पर ऑपरेशन दोबारा निष्पादित हो सकता है। इसलिए टाइमआउट या कोई अन्य 5xx प्रतिक्रिया यह साबित नहीं करती कि ऑपरेशन का कोई असर नहीं हुआ।
SDK का व्यवहार
आधिकारिक SDK हर बदलाव करने वाले अनुरोध के साथ अपने-आप बनी UUID Idempotency-Key जोड़ते हैं। यह हर तार्किक कॉल के लिए एक बार बनती है और उस कॉल के सभी फिर से प्रयासों में दोबारा इस्तेमाल होती है। जब एक तार्किक ऑपरेशन कई SDK कॉल में फैला हो, तो आप हर कॉल के लिए अपनी कुंजी दे सकते हैं (TypeScript में idempotencyKey, Go में option.WithIdempotencyKey, Python में idempotency_key)। रीप्ले पहचानने के लिए, हर SDK के ट्रांसपोर्ट-मेटाडेटा एक्सेसर से Idempotency-Replay प्रतिक्रिया हेडर पढ़ें: TypeScript में .withResponse(), Go में option.WithResponseInto और Python में with_raw_response।
संबंधित
- आइडेम्पोटेंसी की अवधारणाएँ: फिर से प्रयास की रणनीति, कुंजी का डिज़ाइन और रीप्ले की सीमाएँ
- त्रुटि प्रतिक्रियाएँ:
E01004औरE01005को समेटने वाली त्रुटि प्रतिक्रिया - ईमेल संदेश: भेजने वाला एंडपॉइंट, जहाँ कुंजी का सबसे अधिक उपयोग होता है
- SDK की अवधारणाएँ: स्वचालित कुंजी निर्माण और फिर से प्रयास
संबंधित संसाधन
इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।