वेबहुक और API कुंजियाँ¶
प्लगइन लिखे बिना Evey को दूसरे टूल से जोड़ने के दो तरीके: वेबहुक सर्वर के event आपके किसी URL पर भेजता है, और API कुंजी किसी script को आपकी तरह सर्वर को कॉल करने देती है। दोनों एडमिन पैनल में एडमिन बनाता है; यह पेज उस व्यक्ति के लिए है जो इन्हें सेट करता है, और उसके लिए जो receiver या script लिखता है।
event किसी URL पर भेजें¶
एडमिन → वेबहुक → वेबहुक बनाएँ: एक नाम, एक URL, भेजे जाने वाले इवेंट, और सिग्नेचर के लिए एक वैकल्पिक सीक्रेट। परीक्षण एक ping भेजता है और जवाब बताता है।
इवेंट। वेबहुक सभी इवेंट की सदस्यता ले सकता है, या चुनी हुई एक सूची की। फ़ॉर्म हर वह event दिखाता है जो सर्वर प्रकाशित करता है; उनमें से कुछ:
| हिस्सा | इवेंट |
|---|---|
| लाइब्रेरी | library.scan.started, library.scan.completed, media.item.added, media.item.updated, media.item.removed, metadata.refreshed |
| प्लेबैक | playback.started, playback.stopped, media.marked.watched, transcode.started, transcode.failed |
| खाते | user.created, user.login.succeeded, user.login.failed, user.profile.created, user.apikey.created |
| अनुरोध | media.request.created, media.request.answered |
| सर्वर | backup.created, backup.failed, plugin.installed, plugin.error, server.config.changed, transcoding.derived_cache_full (सबटाइटल स्टोर अपनी खाली जगह की सीमा से नीचे) |
जो प्लगइन EmitEvent कॉल करता है, वह plugin.event.<type> प्रकाशित करता है, जो
सभी इवेंट वाले वेबहुक को भी मिलता है।
भेजना। हर event एक JSON POST है, दो header के साथ:
X-Evey-Delivery: एक पहचान जो एक ही भेजने की सारी कोशिशों में एक जैसी रहती है, ताकि आपका receiver दोहराव को अनदेखा कर सके;X-Evey-Signature:sha256=और उसके बाद body का HMAC-SHA256, जो वेबहुक के सीक्रेट से निकाला गया है। इसे उसी सीक्रेट से जाँचें, ताकि पता रहे कि request आपके सर्वर से आया है। सीक्रेट के बिना सिग्नेचर कुछ साबित नहीं करता।
हर कोशिश जवाब के लिए 30 सेकंड तक रुकती है। फ़ेल होने पर 1, 5 और 30 सेकंड बाद फिर
कोशिश होती है। हर कोशिश दर्ज होती है; इतिहास API से पढ़ा जाता है
(प्लगइन API में ListWebhookDeliveries), पैनल में नहीं।
सिर्फ़ सार्वजनिक पते
वेबहुक का URL http या https होना चाहिए और किसी सार्वजनिक पते की ओर होना
चाहिए। localhost, निजी और link-local पते (192.168.x.x, 10.x.x.x,
172.16.x.x...), और ऐसा नाम जो इनमें से किसी पर पहुँचता हो, वेबहुक सहेजते समय
और फिर सर्वर के जुड़ते समय मना होते हैं। इससे सर्वर को आपके अंदरूनी नेटवर्क तक
पहुँचने के लिए इस्तेमाल नहीं किया जा सकता; आपके लोकल नेटवर्क पर receiver को
एक सार्वजनिक पता या एक relay चाहिए।
script से सर्वर को कॉल करें¶
API कुंजी किसी script को बिना पासवर्ड के सर्वर API कॉल करने देती है। कुंजियाँ एडमिन एडमिन → API कुंजियाँ → नई API कुंजी में बनाता है, और वे उसी एडमिन की होती हैं।
- कुंजी एक बार दिखती है, जब बनाई जाती है। उसी समय उसे सहेज लें; वह फिर से नहीं दिखाई जा सकती, सिर्फ़ रद्द करें से रद्द की जा सकती है।
- यह अपने मालिक की तरह काम करती है, एडमिन के अधिकारों के साथ, अपने दायरे के अंदर।
- दायरे (scope) सीमित करते हैं कि कुंजी क्या कर सकती है:
| दायरा | क्या करने देता है |
|---|---|
media:read |
मीडिया का मेटाडेटा पढ़ना |
media:write |
मीडिया बदलना और स्कैन शुरू करना |
playback:read |
प्लेबैक की स्थिति और इतिहास पढ़ना |
playback:write |
प्लेबैक और प्रगति को नियंत्रित करना |
users:read |
उपयोगकर्ता पढ़ना |
users:write |
उपयोगकर्ता बदलना |
admin:read |
प्रशासन की गतिविधि और आँकड़े पढ़ना |
admin:write |
प्रशासन की सेटिंग्स बदलना |
बिना किसी दायरे के बनी कुंजी (सभी (लेगेसी)) के पास गैर-प्रशासनिक method पर पूरी पहुँच होती है, अपने मालिक की तरह, पर प्रशासन वाले method हमेशा अपना दायरा माँगते हैं: लेगेसी कुंजी उन तक नहीं पहुँच सकती। script को जिन दायरों की ज़रूरत है, वही चुनें।
कुंजी Authorization header में जाती है, Bearer के साथ या उसके बिना:
कुंजी रद्द होते ही, या उसका मालिक अक्षम होते ही, तुरंत काम करना बंद कर देती है। endpoint खुद सर्वर API में दिए गए हैं, पहचान के दूसरे तरीकों के साथ।