कस्टम कनेक्टर

कैटलॉग 100+ सेवाओं को कवर करता है, लेकिन हर टीम के पास कुछ आंतरिक टूल या क्षेत्रीय SaaS उत्पाद होते हैं जो उस पर नहीं हैं। कस्टम कनेक्टर इसे हल करते हैं।

आप एक क्रेडेंशियल पंजीकृत करते हैं — एक API key या OAuth क्रेडेंशियल — और Zero को बताते हैं कि सेवा को कैसे कॉल करना है। वहाँ से, Zero आपके कस्टम कनेक्टर को बिल्कुल किसी बिल्ट-इन जैसा ही मानता है: वही ऑडिट लॉग, वही ब्रोकर-एक्सेस प्रॉक्सी, वही संवेदनशील-कार्य गेट।

दो प्रकार

अपनी सेवा से मेल खाने वाला प्रकार चुनें:

• API key — किसी भी ऐसी सेवा के लिए काम करता है जो हेडर में स्टैटिक टोकन से प्रमाणित होती है। सबसे सरल और तेज़ रास्ता: key पेस्ट करें, कनेक्टर को नाम दें, Zero को बेस URL पर इंगित करें। ज़्यादातर आंतरिक API और कई SaaS टूल इसका इस्तेमाल करते हैं।
• OAuth 2.0 — उन सेवाओं के लिए जो OAuth के माध्यम से प्रति-उपयोगकर्ता टोकन जारी करती हैं। आप एक client ID और secret प्रदान करते हैं, उन स्कोप को कॉन्फ़िगर करते हैं जिन्हें आप Zero से अनुरोध करवाना चाहते हैं, और Zero ज़रूरत पड़ने पर प्रति-उपयोगकर्ता OAuth प्रक्रिया चलाता है।

अगर आप निश्चित नहीं हैं कि कौन सा इस्तेमाल करना है, तो अपस्ट्रीम सेवा के API दस्तावेज़ देखें। शब्द "API key" (या "personal access token") का आमतौर पर मतलब प्रकार 1 होता है; "OAuth" (या "client credentials") का आमतौर पर मतलब प्रकार 2 होता है।

API-key कनेक्टर सेट अप करना

1. अपने वर्कस्पेस में Connectors पेज खोलें।
2. Add custom connector → API key पर क्लिक करें।
3. भरें:
   • Name. कुछ ऐसा जिसे Zero प्रॉम्प्ट पढ़ते समय पहचान सके, जैसे internal-billing-api या acme-crm।
   • Base URL. API की जड़: https://api.internal.acme.com।
   • Auth header. आमतौर पर Authorization: Bearer YOUR_TOKEN या X-API-Key: YOUR_TOKEN। जो सेवा अपेक्षा करती है उससे मिलाएँ।
   • API key. क्रेडेंशियल पेस्ट करें। एन्क्रिप्टेड संग्रहीत; सहेजने के बाद कभी दिखाई नहीं देता।
   • Allowed paths (optional). Zero को विशिष्ट एंडपॉइंट तक सीमित करें, जैसे /v1/invoices/*। ब्लास्ट रेडियस कम करता है।
4. Save और Test connection पर क्लिक करें। Zero बेस URL को GET / (या आपके निर्दिष्ट पथ) के साथ पिंग करता है और प्रतिक्रिया की रिपोर्ट देता है।

OAuth 2.0 कनेक्टर सेट अप करना

थोड़ा अधिक काम, लेकिन उन सेवाओं के लिए इसके लायक जहाँ प्रति-उपयोगकर्ता प्राधिकरण मायने रखता है:

1. अपस्ट्रीम सेवा के साथ एक OAuth एप्लिकेशन पंजीकृत करें। आपको एक client ID और client secret मिलेगा। redirect URI को उसी पर सेट करें जो VM0 add-connector फ़ॉर्म पर प्रदर्शित करता है।
2. VM0 में: Add custom connector → OAuth 2.0।
3. भरें:
   • Name और Base URL, ऊपर की तरह
   • अपस्ट्रीम सेवा के OAuth दस्तावेज़ से Authorization URL और Token URL
   • Client ID और Client secret
   • Scopes. उन स्कोप की सूची जिनका Zero को अनुरोध करने की अनुमति है। न्यूनतम का इस्तेमाल करें जो आपके वर्कफ़्लो को कवर करे।
4. सहेजें। इस कनेक्टर की ज़रूरत वाला पहला सत्र प्रति उपयोगकर्ता OAuth प्रवाह को ट्रिगर करता है।

Zero को कस्टम कनेक्टर इस्तेमाल करना कैसे बताएँ

दो तरीके। जो भी आपके वर्कफ़्लो में फ़िट हो उसे चुनें।

जब आप Zero से कुछ करने को कहें तो उसे इनलाइन वर्णित करें:

"चालान #4422 लाने के लिए internal-billing-api कनेक्टर का इस्तेमाल करो। फिर PDF को ops@acme.com पर ईमेल कर दो।"

Zero कनेक्टर स्पेक लोड करता है और पता लगाता है कि कौन सा एंडपॉइंट कॉल करना है। यह इसलिए काम करता है क्योंकि कनेक्टर OpenAPI-शैली के मेटाडेटा के साथ आते हैं (कई सेवाओं के लिए स्वतः-खोजे गए, वैकल्पिक रूप से मैन्युअल रूप से प्रदान किए गए)।

एक ऐसी skill लिखें जो कनेक्टर को नाम से संदर्भित करे। स्किल बॉडी प्रक्रिया का वर्णन करती है; जब विवरण किसी आने वाले अनुरोध से मेल खाता है तो Zero स्किल को स्वतः लोड कर लेता है। दोहराए जाने वाले वर्कफ़्लो के लिए, यह हर बार इनलाइन फिर से वर्णन करने से अधिक साफ़-सुथरा है।

pull-invoice नामक एक स्किल जिसका विवरण "internal-billing-api से एक चालान लाएँ और PDF ईमेल करें" हो — एक बार लिखे जाने पर, जब भी कोई चालान माँगता है Zero उसे इनवोक करता है।

OpenAPI स्पेक और इनलाइन स्कीमा

Zero किसी कस्टम कनेक्टर के साथ सबसे अच्छा काम करता है जब वह उपलब्ध एंडपॉइंट, मेथड और पैरामीटर जानता है। इसे प्रदान करने के तीन तरीके:

• Auto-discover सेवा के /openapi.json या /swagger.json से अगर वह किसी को उजागर करती है। बस Zero को URL पर इंगित करें।
• Upload a spec. एक OpenAPI 3 YAML/JSON पेस्ट या अपलोड करें। Zero इसे पार्स करता है और कॉल तैयार करते समय टूलटिप-शैली का मेटाडेटा प्रदान करता है।
• Inline descriptions. बिना स्पेक वाले आंतरिक टूल के लिए, आप कनेक्टर बॉडी में एक छोटा markdown विवरण लिख सकते हैं — एंडपॉइंट, मेथड, नमूना पेलोड। कच्चा लेकिन कार्यात्मक।

स्पेक के बिना भी, Zero फिर भी काम करता है — उसे बस पैरामीटर आकारों के बारे में अधिक अनुमान लगाना पड़ता है। बार-बार इस्तेमाल किए जाने वाले कस्टम कनेक्टर के लिए, एक स्पेक जल्दी ही अपनी कीमत वसूल कर लेता है।

वर्कस्पेस के बीच साझा करना

कस्टम कनेक्टर डिफ़ॉल्ट रूप से वर्कस्पेस-स्कोप वाले होते हैं। एक ही संगठन में दो टीमें एक ही आंतरिक API के लिए अपना-अपना कस्टम कनेक्टर बनाए रख सकती हैं। उन संगठनों के लिए जो एक विहित सेटअप चाहते हैं:

• Enterprise org-level connectors. एंटरप्राइज़ प्लान पर उपलब्ध। संगठन स्तर पर एक बार सेट अप करें; उस संगठन के अंतर्गत हर वर्कस्पेस में दिखाई देता है। हर किसी द्वारा इस्तेमाल किए जाने वाले आंतरिक API के लिए अनुशंसित।
• Connector package. बहुत बड़े संगठनों के लिए, आंतरिक प्लेटफ़ॉर्म टीम एक कस्टम कनेक्टर को एक संस्करणित पैकेज के रूप में प्रकाशित कर सकती है; वर्कस्पेस इसे इंस्टॉल करते हैं और अपडेट स्वतः उठा लेते हैं।

सुरक्षा और दर सीमाएँ

• Credentials. प्रति-वर्कस्पेस keys के साथ आराम की स्थिति में एन्क्रिप्टेड। सहेजने के बाद कभी दिखाई नहीं देता; केवल फिर से दर्ज करने योग्य।
• Per-call audit. कस्टम कनेक्टर के माध्यम से हर अनुरोध सत्र लॉग में मेथड, URL, स्टेटस कोड और समय के साथ दिखाई देता है।
• Rate limits. अपस्ट्रीम सेवा द्वारा लागू। Zero वर्कस्पेस-कॉन्फ़िगर की गई सीमा तक एक्सपोनेंशियल बैकऑफ़ के साथ 429 प्रतिक्रियाओं को संभालता है।
• Allow-listed paths. वैकल्पिक: Zero को विशिष्ट URL पैटर्न तक सीमित करें। अगर कनेक्टर key अति-विशेषाधिकार प्राप्त है तो ब्लास्ट रेडियस कम करता है।
• Read-only by default. एक नया कस्टम कनेक्टर केवल-पढ़ने के रूप में चिह्नित होता है। राइट एक्सेस देने के लिए प्रति वर्कस्पेस स्पष्ट कॉन्फ़िगरेशन की आवश्यकता होती है।

आम गलतियाँ

• Over-broad API keys. अगर आपकी सेवा इसका समर्थन करती है, तो अपनी व्यक्तिगत एडमिन key को फिर से इस्तेमाल करने के बजाय Zero के लिए एक स्कोप की गई key बनाएँ। रोटेट और ऑडिट करना आसान।
• Missing schemas. OpenAPI स्पेक या इनलाइन विवरण के बिना, Zero पैरामीटर आकारों का अनुमान लगाता है। यह सरल मामलों के लिए काम करता है और नेस्टेड ऑब्जेक्ट के लिए टूट जाता है। जब आप कर सकें तब एक स्पेक प्रदान करें।
• Untested base URLs. सेटअप के बाद हमेशा Test connection पर क्लिक करें। इस चरण में एक 401 या 404 एक महत्वपूर्ण सत्र में 401 से कहीं बेहतर है।
• Forgetting to rotate. keys को हर तिमाही रोटेट करने के लिए एक कैलेंडर रिमाइंडर सेट करें। VM0 में कनेक्टर key रोटेशन एक क्लिक है; अपस्ट्रीम रोटेशन वह है जिसमें अधिकांश समय लगता है।

आगे क्या

• दोहराए जाने वाले कस्टम-कनेक्टर वर्कफ़्लो को कैप्चर करने के लिए Skills देखें।
• कस्टम-कनेक्टर क्रेडेंशियल कैसे संभाले जाते हैं, इसके लिए Permissions देखें।
• कस्टम बनाने से पहले Catalog देखें — आपकी सेवा पहले से समर्थित हो सकती है।