सर्वोत्तम तरीके

पार्टनर इंटीग्रेशन को पूर्वानुमेय, निगरानी योग्य और सुविधाओं के लिए सुरक्षित बनाए रखने के लिए इन पैटर्न का उपयोग करें।

सुविधाओं की पहचान सुसंगत रूप से करें

अपने पार्टनर खाते के लिए कॉन्फ़िगर की गई लिंकिंग विधि चुनें और उसका सुसंगत रूप से उपयोग करें:

• Direct Link - सुविधाओं वाले एंडपॉइंट द्वारा लौटाए गए Performance Hub facility_id का उपयोग करें।
• Linking Identifier - अपने स्वयं के स्थान पहचानकर्ता का उपयोग करें, जैसे ब्रांच ID, स्थान कोड या स्टोर नंबर।

एक ही अनुरोध में दोनों पहचानकर्ता न भेजें। Performance Hub आपके पार्टनर खाते के लिए कॉन्फ़िगर की गई लिंकिंग विधि का उपयोग करके अनुरोधों को हल करता है।

सेटअप मार्गदर्शन के लिए पार्टनर लिंकिंग विधियाँ देखें।

बैच राइट सावधानी से करें

Partner API, JSON अनुरोध बॉडी स्वीकार करता है और जहाँ प्रलेखित है, वहाँ बैच-आधारित सिंक वर्कफ़्लो के लिए डिज़ाइन किया गया है। बैचों को सीमित और पुनः प्रयास योग्य रखें।

डिफ़ॉल्ट दिशानिर्देश:

• बेहतर प्रदर्शन के लिए प्रति बैच अनुरोध अधिकतम 1000 आइटम का उपयोग करें।
• पेलोड को 10MB से कम रखें।
• प्रति एंडपॉइंट प्रति सेकंड 5 अनुरोधों की सीमा के भीतर रहें।

रेट लिमिट समायोज्य हैं और आपके Performance Hub पार्टनर अकाउंट मैनेजर द्वारा हर मामले के अनुसार कॉन्फ़िगर की जा सकती हैं। यदि आप बड़ी मात्रा में इम्पोर्ट, लॉन्च ट्रैफ़िक या रिपोर्टिंग बैकफ़िल की अपेक्षा करते हैं, तो बदलाव की समयावधि से पहले आवश्यक थ्रूपुट पर सहमति बना लें।

यदि आपको कोई बड़ा डेटासेट सिंक करना है, तो उसे निर्धारित (deterministic) हिस्सों में बाँटें और अपनी ओर हर हिस्से की ID लॉग करें। इससे विफल पुनःप्रयासों को समझना आसान हो जाता है।

सुरक्षित रूप से पुनः प्रयास करें

429, 500, 502, 503 और 504 जैसी अस्थायी विफलताओं के लिए एक्सपोनेंशियल बैकऑफ़ का उपयोग करें।

लगातार तेज़ पुनःप्रयास लूप से बचें। शुरुआत के लिए एक अच्छा तरीका है:

1. 1 सेकंड के बाद पुनः प्रयास करें।
2. 2 सेकंड के बाद पुनः प्रयास करें।
3. 4 सेकंड के बाद पुनः प्रयास करें।
4. यदि ऑपरेशन फिर भी विफल होता है, तो रुकें और अलर्ट भेजें।

400 या 422 जैसी सत्यापन विफलताओं के लिए, पुनः प्रयास करने से पहले अनुरोध ठीक करें।

जहाँ समर्थित हो, वहाँ आइडेम्पोटेंसी का उपयोग करें

Door/Gate Controller अनलॉक एंडपॉइंट एक वैकल्पिक idempotency_key का समर्थन करता है। समान पार्टनर, सुविधा और दरवाज़े के लिए समान कुंजी का दोबारा उपयोग करने पर, उपलब्ध होने पर मौजूदा परिणाम लौटाया जाता है।

की जा रही कार्रवाई के लिए एक स्थिर कुंजी का उपयोग करें, उदाहरण के लिए आपके सिस्टम की कोई चेक-इन ID या एक्सेस इवेंट ID।

यह न मानें कि हर राइट एंडपॉइंट आइडेम्पोटेंसी का समर्थन करता है, जब तक कि उस एंडपॉइंट के लिए यह प्रलेखित न हो।

स्रोत डेटा को साफ़ रखें

जहाँ भी संभव हो, स्थिर और सामान्यीकृत मान भेजें:

• अपने स्रोत सिस्टम से सुसंगत सदस्य, प्लान, सुविधा और चेक-इन ID का उपयोग करें।
• तारीखों और समय के लिए ISO 8601 टाइमस्टैम्प का उपयोग करें।
• जहाँ उपलब्ध हो, फ़ोन नंबर अंतरराष्ट्रीय प्रारूप में भेजें।
• हर एंडपॉइंट के लिए प्रलेखित फ़ील्ड का उपयोग करके मुद्राएँ भेजें।
• फ़्री-टेक्स्ट फ़ील्ड में ऐसा डेटा भरने से बचें जो संरचित फ़ील्ड में होना चाहिए।

इंक्रीमेंटल और पूर्ण सिंक के लिए डिज़ाइन करें

अधिकांश पार्टनर इंटीग्रेशन को दोनों की आवश्यकता होती है:

• दिन-प्रतिदिन के बदलावों के लिए इंक्रीमेंटल सिंक।
• छूटे हुए इवेंट, ऐतिहासिक इम्पोर्ट या डेटा ड्रिफ़्ट को ठीक करने के लिए पूर्ण रिकंसिलिएशन सिंक।

आपका इंटीग्रेशन किसी सदस्य, सदस्यता प्लान या रिपोर्ट स्नैपशॉट की वर्तमान स्थिति को, किसी पिछले अनुरोध के सफल होने पर निर्भर हुए बिना, दोबारा भेजने में सक्षम होना चाहिए।

Access Time Windows सुरक्षित रूप से प्रकाशित करें

हर सदस्य के access_time_windows मान को एक पूर्ण, स्वतंत्र रूप से संशोधित स्नैपशॉट मानें:

• इंक्रीमेंटल और रिकंसिलिएशन वर्कर्स में एक ही, लगातार बढ़ने वाली access_time_windows_revision स्ट्रीम का समन्वय करें।
• अनिश्चित या अस्थायी डिलीवरी को उसी रिविज़न और सामान्यीकृत पेलोड के साथ पुनः प्रयास करें।
• जब आप access_time_windows अपडेट नहीं कर रहे हों, तो उसे छोड़ दें।
• [] केवल तब भेजें जब किसी सफल आधिकारिक स्रोत फ़ेच से यह सिद्ध हो जाए कि कोई विंडो शेष नहीं है। अपस्ट्रीम टाइमआउट, आंशिक परिणाम या पार्स विफलता को कभी भी रद्दीकरण में न बदलें।
• external_id और scope_key को स्थिर रखें, और प्रोडक्शन से पहले हर स्कोप मैपिंग को प्रमाणित करें।
• उस इंटीग्रेशन के लिए तय की गई ताज़गी नीति के अनुसार स्रोत की आयु की निगरानी करें।

पूर्ण स्नैपशॉट, टाइमज़ोन, DST, रद्दीकरण और टेस्ट वेक्टर के लिए आधिकारिक Access Time Windows प्रोड्यूसर गाइड देखें।

एक्सेस कंट्रोल को सुरक्षा-महत्वपूर्ण मानें

Door/Gate Controller अनलॉक के लिए:

• Performance Hub को कॉल करने से पहले आपके सिस्टम को तय करना होगा कि व्यक्ति को प्रवेश की अनुमति है या नहीं।
• Performance Hub 200 केवल तब लौटाता है जब ऑन-साइट कंट्रोलर पुष्टि करता है कि रिले भौतिक रूप से अनलॉक हो गया है।
• अधिकांश पुष्टियाँ 3-5 सेकंड में पूरी हो जाती हैं।
• टाइमआउट एक स्पष्ट विफल अनलॉक है, बैकग्राउंड में हुई सफलता नहीं।
• केवल अपने स्वयं के एक्सेस और सुरक्षा नियमों के अनुसार ही पुनः प्रयास करें।

अनलॉक एंडपॉइंट द्वारा लौटाए गए event_id और command_id को हमेशा लॉग करें।

अपने इंटीग्रेशन की निगरानी करें

डेवलपमेंट और लॉन्च के दौरान Partner Console के अनुरोध लॉग का उपयोग करें। प्रोडक्शन में, इन जानकारियों के साथ अपने स्वयं के लॉग भी रखें:

• अनुरोध का टाइमस्टैम्प।
• एंडपॉइंट।
• स्रोत रिकॉर्ड ID।
• सुविधा पहचानकर्ता।
• HTTP स्टेटस कोड।
• Performance Hub रिस्पॉन्स बॉडी या त्रुटि संदेश।

जब कोई ग्राहक पूछता है कि क्या हुआ, तो ये फ़ील्ड सहायता और रिकंसिलिएशन को बहुत तेज़ बना देते हैं।