KapsuleHost आपको दो डेवलपर सर्फेस देता है: आपके खाते को प्रोग्रामेटिक रूप से पढ़ने के लिए स्कोप्ड API कुंजियाँ, और एक रिमोट बिल्ड कैश जो आपकी अपनी मशीनों और CI रनर्स पर Turborepo और Nx बिल्ड को तेज़ करता है।
न तो डिफ़ॉल्ट रूप से सक्षम है। दोनों Settings से बनाए जाते हैं, और दोनों आपको एक गुप्त बिल्कुल एक बार देते हैं।
API कुंजी बनाना
API कुंजियाँ Settings के अंदर, फिर Security के तहत, API कुंजियाँ कार्ड में रहती हैं।
- Settings पर जाएँ, फिर Security।
- API कुंजियाँ तक स्क्रॉल करें और नई कुंजी पर क्लिक करें।
- कुंजी को एक नाम दें। फ़ील्ड "कुंजी का नाम (उदाहरण के लिए मेरी ऑटोमेशन स्क्रिप्ट)" सुझाता है। नाम केवल आपके लिए है, इसलिए इसे कहीं बताएँ कि कुंजी कहाँ उपयोग की जाएगी।
- स्कोप चिप्स पर क्लिक करें यह चुनने के लिए कि कुंजी क्या कर सकती है। तीन रीड स्कोप पहले से चुने गए हैं:
read:sites,read:email, औरread:domains। इसे जोड़ने या हटाने के लिए एक चिप पर क्लिक करें। - Create पर क्लिक करें।
पूरी कुंजी एक बार दिखाई देती है, "अभी कॉपी करें" शीर्षक वाले हरे पैनल में। इसे सीधे अपने गुप्त स्टोर में कॉपी करें। जब आप उस पैनल को बंद करते हैं तो कुंजी चली जाती है: केवल एक छोटा उपसर्ग रखा जाता है, जो सब कुछ सूची कभी भी आपको फिर से दिखा सकती है।
कुंजी दूसरी बार कभी प्रदर्शित नहीं होती है और इसे पुनर्प्राप्त नहीं किया जा सकता। यदि आप इसे खो देते हैं, तो उस कुंजी को रद्द करें और एक नई बनाएँ। इसे साझा दस्तावेज़, टिकट, कमिट या चैट संदेश में पेस्ट न करें।
केवल Owner और Admin भूमिकाएँ कुंजी बना सकती हैं। कोई अन्य भूमिका अनुमति त्रुटि प्राप्त करती है। जब कुंजी बनाई जाती है, तो एक सुरक्षा सतर्क ईमेल उस व्यक्ति के पते पर जाता है जिसने इसे बनाया था, इसलिए उनमें से एक अप्रत्याशित तत्काल जांचने लायक है।
स्कोप्स
सात स्कोप्स दिए गए हैं:
| स्कोप | अनुदान देता है |
|---|---|
read:sites | आपकी वेबसाइटें पढ़ना |
write:sites | वेबसाइटों पर लेखन संचालन के लिए आरक्षित |
read:email | आपके मेलबॉक्स पढ़ना |
write:email | मेलबॉक्स पर लेखन संचालन के लिए आरक्षित |
read:domains | आपके डोमेन पढ़ना |
write:domains | डोमेन पर लेखन संचालन के लिए आरक्षित |
read:billing | बिलिंग डेटा पढ़ने के लिए आरक्षित |
ग्राहक API आज केवल पढ़ने के लिए है। write: स्कोप्स और read:billing कुंजी पर चुने जा सकते हैं, लेकिन कोई ग्राहक अंतिम बिंदु वर्तमान में उनका उपभोग नहीं करता है, इसलिए उन्हें अनुदान देना कुछ नहीं बदलता। केवल रीड स्कोप्स अनुदान दें जिनकी आपको वास्तव में आवश्यकता है और लेखन अंतिम बिंदु भेजे जाने पर कुंजी पर फिर से जाएँ।
कुंजी का उपयोग करना
Authorization हेडर पर वाहक टोकन के रूप में कुंजी भेजें।
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
तीन अंतिम बिंदु ग्राहक API कुंजी स्वीकार करते हैं:
| अंतिम बिंदु | आवश्यक स्कोप | रिटर्न करता है |
|---|---|---|
GET /api/v1/sites | read:sites | आपकी वेबसाइटें, डोमेन, एप्लिकेशन प्रकार और स्थिति के साथ |
GET /api/v1/domains | read:domains | आपके डोमेन, स्थिति और समाप्ति के साथ |
GET /api/v1/mailboxes | read:email | आपके मेलबॉक्स |
कोई कुंजी, एक अज्ञात कुंजी, या रद्द की गई कुंजी वाला अनुरोध 401 रिटर्न करता है। सही स्कोप के बिना एक वैध कुंजी 403 रिटर्न करती है, आवश्यक स्कोप का नाम देते हुए एक संदेश के साथ। हर सफल कॉल कुंजी की अंतिम-उपयोग की गई टाइमस्टैम्प को अपडेट करता है।
धीरे पोल करें। ये अंतिम बिंदु लाइव खाता डेटा पढ़ते हैं, और उनके विरुद्ध एक तंग लूप दुरुपयोग से अप्रभेद्य है। किसी भी चीज़ के लिए जो डैशबोर्ड को चाहिए उसके लिए एक बार एक मिनट उदार है; एक घंटा में एक बार आमतौर पर काफी है।
कुंजियों की समीक्षा और रद्द करना
API कुंजियाँ तालिका प्रत्येक सक्रिय कुंजी को Name, Prefix (कुंजी की दृश्यमान शुरुआत), और Scopes द्वारा सूचीबद्ध करती है। इसे मारने के लिए एक पंक्ति के अंत में Revoke पर क्लिक करें।
रद्द करना तत्काल प्रभाव डालता है और कोई पुष्टि संवाद नहीं है। अगला अनुरोध उस कुंजी का उपयोग करके 401 के साथ विफल रहता है। एक रद्द की गई कुंजी को पुनर्स्थापित नहीं किया जा सकता है, इसलिए क्लिक करने से पहले सुनिश्चित करें कि आप जानते हैं कि यह क्या उपयोग कर रहा है।
कुंजियाँ account की हैं, उस व्यक्ति की नहीं जिसने उन्हें बनाया था। टीम पृष्ठ से एक साथी को हटाने से वह कुंजियाँ रद्द नहीं होती हैं जो उन्होंने बनाई हैं। अपने ऑफबोर्डिंग में एक कुंजी समीक्षा बनाएँ: व्यक्ति को हटाएँ, फिर यहाँ आएँ और कुछ भी रद्द करें जो उन्होंने बनाया है।
कुंजी निर्माण और रद्दीकरण दोनों ऑडिट लॉग में api_key.* क्रियाओं के तहत रिकॉर्ड किए जाते हैं, अभिनेता और मूल IP पते के साथ।
रिमोट बिल्ड कैश
Developer पृष्ठ, सेटिंग्स रेल के Advanced समूह में, Remote Build Cache प्रदान करता है। पैनल इसे "Turborepo और Nx बिल्ड को मशीनों और CI पाइपलाइनों में एक वितरित कैश साझा करके तेज़ करें" के रूप में वर्णित करता है।
- Settings पर जाएँ, फिर Developer।
- Remote cache सक्षम करें पर क्लिक करें।
- "नया टोकन तैयार किया गया। इसे अभी कॉपी करें, यह फिर से नहीं दिखाया जाएगा" शीर्षक वाले पैनल से टोकन कॉपी करें।
फिर अपने CI कॉन्फ़िगरेशन या स्थानीय .env.local में दो पर्यावरण चर सेट करें:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
टीम ID आपकी KapsuleHost खाता ID है, जो उसी पृष्ठ पर सेटअप निर्देशों में दिखाई देती है।
पृष्ठ अपनी अपनी संगतता बताता है: Turborepo 1.x और बाद में, Nx 16 और बाद में, और कोई भी उपकरण समान रिमोट कैश प्रोटोकॉल लागू करना। कलाकृतियाँ प्रति खाते संग्रहीत की जाती हैं और कभी भी खातों में साझा नहीं की जाती हैं।
दो अन्य नियंत्रण कार्ड पर बैठते हैं:
- टोकन घुमाएँ एक नया टोकन जारी करता है और पुरानी कुंजी को अमान्य करता है। कोई भी CI काम जो अभी भी पुरानी कुंजी को धारण कर रहा है कैश का उपयोग करना बंद कर देता है, इसलिए अपने रहस्यों के साथ घुमाएँ और अपडेट करें।
- Disable कैश को पूरी तरह से बंद कर देता है।
दोनों के बीच चुनाव करना
वे असंबंधित समस्याओं को हल करते हैं और परस्पर विनिमेय नहीं हैं।
एक API कुंजी का उपयोग करें जब KapsuleHost के बाहर कुछ आपके खाते की स्थिति जानने की आवश्यकता है: एक स्थिति बोर्ड जो आपकी साइटों को सूचीबद्ध करता है, एक स्क्रिप्ट जो आपको शीघ्र ही समाप्त होने वाले डोमेन के बारे में चेतावनी देता है, एक सूची निर्यात।
रिमोट बिल्ड कैश का उपयोग करें जब आपका निर्माण धीमा है क्योंकि हर मशीन और हर CI रन अपरिवर्तित पैकेज को फिर से बनाता है। इसका आपकी होस्ट की गई साइटों से कोई संबंध नहीं है और आपके खाता डेटा को नहीं पढ़ता है।
समस्या निवारण
हर अनुरोध 401 रिटर्न करता है। पुष्टि करें कि आपने हेडर को Authorization: Bearer <key> के रूप में एक एकल स्थान के साथ भेजा है, कि कुंजी को कॉपी करते समय छोटा नहीं किया गया था, और कि इसे रद्द नहीं किया गया है। आपकी कुंजी की शुरुआत को Prefix कॉलम के साथ तुलना करें यह सुनिश्चित करने के लिए कि आप उस कुंजी का उपयोग कर रहे हैं जो आप सोचते हैं।
एक अनुरोध 403 एक स्कोप का नाम देते हुए रिटर्न करता है। कुंजी में वह स्कोप नहीं है। स्कोप्स कुंजी बनाए जाने के समय निर्धारित होते हैं, इसलिए सही स्कोप्स के साथ एक प्रतिस्थापन बनाएँ और पुरानी को रद्द करें।
मुझे API कुंजियाँ कार्ड नहीं दिखाई दे रहा है। यह सुरक्षा पृष्ठ पर है, डेवलपर पृष्ठ पर नहीं। डेवलपर पृष्ठ केवल बिल्ड कैश रखता है।
नई कुंजी बटन कुछ नहीं करता है। आपकी भूमिका Admin से नीचे है। Owner या Admin से पूछें।
बिल्ड कैश को हिट नहीं कर रहे हैं। पुष्टि करें कि TURBO_TOKEN और TURBO_TEAM दोनों बिल्ड पर्यावरण में मौजूद हैं, कि टोकन को घुमाया नहीं गया है क्योंकि आपने इसे सेट किया था, और पृष्ठ अभी भी Active बैज दिखाता है।
एक कुंजी जो मैंने नहीं बनाई है दिखाई दी। इसे एक समझौते के रूप में मानें। इसे रद्द करें, फिर Account Security के माध्यम से काम करें और ऑडिट लॉग की जाँच करें कि और क्या बदला गया।