इवेंट एसिंक्रोनस होते हैं और इन्हें Google Cloud Pub/Sub मैनेज करता है. हर Projectके लिए, इवेंट एक ही विषय में होते हैं. इवेंट से सभी डिवाइसों और स्ट्रक्चर के लिए अपडेट मिलते हैं. साथ ही, इवेंट मिलने की पुष्टि तब तक की जाती है, जब तक उपयोगकर्ता ने ऐक्सेस टोकन रद्द नहीं किया है और इवेंट मैसेज की समयसीमा खत्म नहीं हुई है.
इवेंट सक्षम करें
इवेंट, SDM API की एक वैकल्पिक सुविधा है. इवेंट को अपने लिए चालू करने का तरीका जानने के लिए, इवेंट चालू करें देखें Project.
Google Cloud Pub/Sub
Pub/Sub के काम करने के तरीके के बारे में ज़्यादा जानने के लिए, Google Cloud Pub/Sub का दस्तावेज़ देखें. खास तौर पर:
- Pub/Sub के बारे में बुनियादी बातें जानने के लिए, इस्तेमाल करने के तरीके देखें.
- पुष्टि करने की सुविधा के काम करने का तरीका समझें.
- उपलब्ध कराई गई क्लाइंट लाइब्रेरी चुनें या अपनी लाइब्रेरी लिखें और REST/एचटीटीपी या gRPC API के प्लैटफ़ॉर्म का इस्तेमाल करें.
इवेंट की सदस्यता
जब आपके Projectके लिए इवेंट चालू किए जाते हैं, तो आपको उस Project आईडी के हिसाब से एक विषय मिलेगा. यह विषय इस तरह दिखेगा:
projects/sdm-prod/topics/enterprise-project-id
इवेंट पाने के लिए, अपने इस्तेमाल के उदाहरण के आधार पर, उस विषय के लिए पुल या पुश सदस्यता बनाएं. एसडीएम विषय की कई सदस्यताएं ली जा सकती हैं. ज़्यादा जानकारी के लिए, सदस्यताएं मैनेज करना देखें.
इवेंट शुरू करना
Pub/Sub सदस्यता बनाने के बाद, पहली बार इवेंट शुरू करने के लिए, एक बार ट्रिगर करने के तौर पर
devices.list
एपीआई कॉल करें. इस कॉल के बाद, सभी स्ट्रक्चर और डिवाइसों के लिए इवेंट पब्लिश हो जाएंगे.
उदाहरण के लिए, 'आसानी से सीखें' गाइड में, अनुमति दें पेज देखें.
इवेंट का क्रम
Pub/Sub, इवेंट के क्रम में डिलीवरी करने की गारंटी नहीं देता. साथ ही, हो सकता है कि इवेंट पाने का क्रम,
उस क्रम से मेल न खाए जिसमें इवेंट असल में हुए थे. इवेंट के क्रम को मिलान करने में मदद पाने के लिए, timestamp
फ़ील्ड का इस्तेमाल करें. इवेंट अलग-अलग या एक इवेंट मैसेज में भी आ सकते हैं.
ज़्यादा जानकारी के लिए, मैसेज का क्रम तय करना लेख पढ़ें.
यूज़र आईडी
अगर आपने उपयोगकर्ताओं के आधार पर (स्ट्रक्चर या डिवाइस के बजाय) लागू किया है, तो संसाधनों और इवेंट को जोड़ने के लिए, इवेंट पेलोड के userID
फ़ील्ड का इस्तेमाल करें. यह फ़ील्ड, किसी खास उपयोगकर्ता को दिखाने वाला आईडी है.
userID
, हर एपीआई कॉल के एचटीटीपी रिस्पॉन्स हेडर में भी उपलब्ध होता है.
रिलेशन इवेंट
रिलेशन इवेंट, किसी संसाधन के लिए रिलेशनल अपडेट दिखाते हैं. उदाहरण के लिए, जब किसी डिवाइस को किसी स्ट्रक्चर में जोड़ा जाता है या किसी डिवाइस को स्ट्रक्चर से मिटाया जाता है.
रिलेशन इवेंट तीन तरह के होते हैं:
- CREATED
- हटा दिया गया
- अपडेट कर दिया गया है
रिलेशन इवेंट का पेलोड इस तरह का होता है:
पेलोड
{ "eventId" : "d5c0f0bd-de65-44fd-ac60-686c302e56eb", "timestamp" : "2019-01-01T00:00:01Z", "relationUpdate" : { "type" : "CREATED", "subject" : "enterprises/project-id/structures/structure-id", "object" : "enterprises/project-id/devices/device-id" }, "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" }
रिलेशन इवेंट में, object
वह रिसॉर्स होता है जिसने इवेंट को ट्रिगर किया है और
subject
वह रिसॉर्स होता है जिसके साथ object
का अब संबंध है. ऊपर दिए गए उदाहरण में, user ने इस डिवाइस का ऐक्सेस developerको दिया है. साथ ही, userका अनुमति वाला डिवाइस अब अनुमति वाले स्ट्रक्चर से जुड़ा है, जिससे इवेंट ट्रिगर होता है.
subject
सिर्फ़ एक कमरा या स्ट्रक्चर हो सकता है. अगर a developer के पास userके स्ट्रक्चर को देखने की अनुमति नहीं है, तो subject
हमेशा खाली रहेगा.
फ़ील्ड
फ़ील्ड | ब्यौरा | डेटा टाइप |
---|---|---|
eventId |
इवेंट के लिए यूनीक आइडेंटिफ़ायर. | string उदाहरण: "64b87b46-1aec-42a4-8c01-997a407814df" |
timestamp |
इवेंट होने का समय. | string उदाहरण: "2019-01-01T00:00:01Z" |
relationUpdate |
यह एक ऐसा ऑब्जेक्ट है जिसमें संबंध के अपडेट के बारे में जानकारी होती है. | object |
userId |
उपयोगकर्ता की पहचान करने वाला यूनीक और बदला हुआ आइडेंटिफ़ायर. | string उदाहरण: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" |
अलग-अलग तरह के इवेंट और उनके काम करने के तरीके के बारे में ज़्यादा जानने के लिए, इवेंट देखें.
उदाहरण
अलग-अलग तरह के रिलेशन इवेंट के लिए, इवेंट पेलोड अलग-अलग होते हैं:
बनाया गया
स्ट्रक्चर बनाया गया
"relationUpdate" : { "type" : "CREATED", "subject" : "", "object" : "enterprises/project-id/structures/structure-id" }
डिवाइस बनाया गया
"relationUpdate" : { "type" : "CREATED", "subject" : "enterprises/project-id/structures/structure-id", "object" : "enterprises/project-id/devices/device-id" }
डिवाइस बनाया गया
"relationUpdate" : { "type" : "CREATED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
अपडेट कर दिया गया है
डिवाइस को रजिस्टर किया गया
"relationUpdate" : { "type" : "UPDATED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
हटा दिया गया
स्ट्रक्चर मिटाया गया
"relationUpdate" : { "type" : "DELETED", "subject" : "", "object" : "enterprises/project-id/structures/structure-id" }
डिवाइस मिटा दिया गया
"relationUpdate" : { "type" : "DELETED", "subject" : "enterprises/project-id/structures/structure-id", "object" : "enterprises/project-id/devices/device-id" }
डिवाइस मिटा दिया गया
"relationUpdate" : { "type" : "DELETED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
रिलेशन इवेंट तब नहीं भेजे जाते, जब:
- कोई रूम मिटाया जाता है
संसाधन इवेंट
रिसॉर्स इवेंट, किसी रिसॉर्स से जुड़े अपडेट को दिखाता है. यह किसी ट्रीट फ़ील्ड की वैल्यू में हुए बदलाव के जवाब में हो सकता है. जैसे, थर्मोस्टैट का मोड बदलना. यह किसी ऐसी डिवाइस कार्रवाई को भी दिखा सकता है जो किसी ट्रीट फ़ील्ड को बदलती नहीं है. जैसे, डिवाइस के बटन को दबाना.
ट्रेट फ़ील्ड की वैल्यू में हुए बदलाव के जवाब में जनरेट किए गए इवेंट में, डिवाइस के GET कॉल की तरह ही एक
traits
ऑब्जेक्ट होता है:
पेलोड
{
"eventId" : "a88bc884-d2b8-42d6-adba-b7be92c232a3",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : {
"name" : "enterprises/project-id/devices/device-id",
"traits" : {
"sdm.devices.traits.ThermostatMode
" : {
"mode" : "COOL"
}
}
},
"userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"resourceGroup" : [
"enterprises/project-id/devices/device-id"
]
}
किसी भी ट्रेइट फ़ील्ड में बदलाव करने वाले संसाधन वाले इवेंट के लिए, पेलोड फ़ॉर्मैट को समझने के लिए, अलग-अलग ट्रैइट के दस्तावेज़ का इस्तेमाल करें.
किसी ऐसे डिवाइस ऐक्शन के जवाब में जनरेट किए गए इवेंट में भी resourceUpdate
ऑब्जेक्ट वाला पेलोड होता है. हालांकि, इसमें traits
ऑब्जेक्ट के बजाय events
ऑब्जेक्ट होता है:
पेलोड
{ "eventId" : "4f80de08-1b77-42a4-b33e-40876a2a1865",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion
" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "MWJ253hZMPAsJZJWbrGM4ThsKM...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }
इस तरह के संसाधन इवेंट, खास विशेषताओं में तय किए जाते हैं. उदाहरण के लिए, मोशन इवेंट को CameraMotion ट्रैट में तय किया गया है. इस तरह के रिसॉर्स इवेंट के लिए पेलोड फ़ॉर्मैट को समझने के लिए, हर ट्रैट का दस्तावेज़ देखें.
फ़ील्ड
फ़ील्ड | ब्यौरा | डेटा टाइप |
---|---|---|
eventId |
इवेंट के लिए यूनीक आइडेंटिफ़ायर. | string उदाहरण: "4f80de08-1b77-42a4-b33e-40876a2a1865" |
timestamp |
इवेंट होने का समय. | string उदाहरण: "2019-01-01T00:00:01Z" |
resourceUpdate |
ऐसा ऑब्जेक्ट जिसमें संसाधन के अपडेट के बारे में जानकारी होती है. | object |
userId |
उपयोगकर्ता की पहचान करने वाला यूनीक और बदला हुआ आइडेंटिफ़ायर. | string उदाहरण: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" |
eventThreadId |
इवेंट थ्रेड के लिए यूनीक आइडेंटिफ़ायर. | string उदाहरण: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59" |
eventThreadState |
इवेंट थ्रेड की स्थिति. | string वैल्यू: "STARTED", "UPDATED", "ENDED" |
resourceGroup |
ऐसा ऑब्जेक्ट जो उन संसाधनों के बारे में बताता है जिनमें इस इवेंट से मिलते-जुलते अपडेट हो सकते हैं. इवेंट का रिसॉर्स (resourceUpdate ऑब्जेक्ट से) हमेशा इस ऑब्जेक्ट में मौजूद रहेगा. |
object |
अलग-अलग तरह के इवेंट और उनके काम करने के तरीके के बारे में ज़्यादा जानने के लिए, इवेंट देखें.
अपडेट की जा सकने वाली सूचनाएं
रिसॉर्स इवेंट के आधार पर सूचनाएं, किसी ऐप्लिकेशन में लागू की जा सकती हैं. जैसे, Android या iOS के लिए. भेजी जाने वाली सूचनाओं की संख्या कम करने के लिए, अपडेट की जा सकने वाली सूचनाएं नाम की सुविधा लागू की जा सकती है. इसमें, मौजूदा सूचनाओं को उसी इवेंट थ्रेड में होने वाले बाद के इवेंट के आधार पर, नई जानकारी के साथ अपडेट किया जाता है.चुनिंदा इवेंट में, अपडेट की जा सकने वाली सूचनाओं की सुविधा काम करती है. साथ ही, इन्हें दस्तावेज़ में अपडेट की जा सकने वाली eventThreadId
नाम का एक अतिरिक्त फ़ील्ड होता है. इस फ़ील्ड का इस्तेमाल करके, अलग-अलग इवेंट को एक-दूसरे से लिंक करें. इससे, किसी उपयोगकर्ता को दिखाई गई मौजूदा सूचना को अपडेट किया जा सकता है.
इवेंट थ्रेड और इवेंट सेशन, दोनों अलग-अलग चीज़ें हैं. इवेंट थ्रेड, उसी थ्रेड में किसी पिछले इवेंट के अपडेट किए गए स्टेटस की पहचान करता है. इवेंट सेशन, एक-दूसरे से जुड़े अलग-अलग इवेंट की पहचान करता है. साथ ही, किसी इवेंट सेशन के लिए कई इवेंट थ्रेड हो सकती हैं.
सूचना के मकसद से, अलग-अलग तरह के इवेंट को अलग-अलग 'थ्रेड' में बांटा जाता है.
थ्रेड ग्रुप करने और समय तय करने का लॉजिक, Google मैनेज करता है. इसे किसी भी समय बदला जा सकता है. SDM API से मिलने वाली इवेंट थ्रेड और सेशन के आधार पर, developer को सूचनाएं अपडेट करनी चाहिए.
थ्रेड की स्थिति
जिन इवेंट के लिए सूचनाएं अपडेट की जा सकती हैं उनमें एक eventThreadState
फ़ील्ड भी होता है. इससे उस समय इवेंट थ्रेड की स्थिति का पता चलता है. इस फ़ील्ड में ये वैल्यू हो सकती हैं:
- STARTED — किसी इवेंट थ्रेड में पहला इवेंट.
- अपडेट किया गया — किसी चल रही इवेंट थ्रेड में मौजूद इवेंट. किसी एक थ्रेड में, इस स्टेटस वाले एक या उससे ज़्यादा इवेंट हो सकते हैं.
- खत्म हो गया — इवेंट थ्रेड में मौजूद आखिरी इवेंट. यह थ्रेड के टाइप के आधार पर, आखिरी बार अपडेट किए गए इवेंट का डुप्लीकेट हो सकता है.
इस फ़ील्ड का इस्तेमाल, किसी इवेंट थ्रेड की प्रोग्रेस और उसके खत्म होने का समय ट्रैक करने के लिए किया जा सकता है.
इवेंट फ़िल्टर करना
कुछ मामलों में, किसी डिवाइस से पता लगाए गए इवेंट को SDM Pub/Sub विषय पर पब्लिश करने से फ़िल्टर किया जा सकता है. इस व्यवहार को इवेंट फ़िल्टर करना कहा जाता है. इवेंट को फ़िल्टर करने का मकसद, कम समय में एक जैसे कई इवेंट मैसेज पब्लिश होने से रोकना है.
उदाहरण के लिए, किसी शुरुआती मोशन इवेंट के लिए, एसडीएम विषय पर मैसेज पब्लिश किया जा सकता है. इसके बाद, मोशन के लिए भेजे गए अन्य मैसेज, तय समय तक पब्लिश नहीं किए जाएंगे. तय समय बीत जाने के बाद, उस इवेंट टाइप के लिए इवेंट मैसेज फिर से पब्लिश किया जा सकता है.
Google Home ऐप्लिकेशन (GHA) में, फ़िल्टर किए गए इवेंट अब भी userके इवेंट इतिहास में दिखेंगे. हालांकि, इस तरह के इवेंट से ऐप्लिकेशन सूचना जनरेट नहीं होती. भले ही, सूचना का वह टाइप चालू हो.
हर तरह के इवेंट का अपना इवेंट फ़िल्टर करने का लॉजिक होता है. इसे Google तय करता है और इसमें कभी भी बदलाव किया जा सकता है. इवेंट फ़िल्टर करने का यह लॉजिक, इवेंट थ्रेड और सेशन लॉजिक से अलग होता है.
सेवा खाते
हमारा सुझाव है कि SDM API की सदस्यताओं और इवेंट मैसेज को मैनेज करने के लिए, सर्विस खातों का इस्तेमाल करें. सेवा खाते का इस्तेमाल कोई व्यक्ति नहीं करता, बल्कि कोई ऐप्लिकेशन या वर्चुअल मशीन करता है. साथ ही, इसकी अपनी एक यूनीक खाता कुंजी होती है.
Pub/Sub API के लिए सेवा खाते की अनुमति देने के लिए, दो लेग वाले OAuth (2LO) का इस्तेमाल किया जाता है.
दो चरणों में अनुमति देने के फ़्लो में:
- developer , सेवा कुंजी का इस्तेमाल करके ऐक्सेस टोकन का अनुरोध करता है.
- developer , एपीआई के कॉल के साथ ऐक्सेस टोकन का इस्तेमाल करता है.
Google 2LO और इसे सेट अप करने के तरीके के बारे में ज़्यादा जानने के लिए, सर्वर से सर्वर ऐप्लिकेशन के लिए OAuth 2.0 का इस्तेमाल करना लेख पढ़ें.
अनुमति देना
सेवा खाते को Pub/Sub API के साथ इस्तेमाल करने की अनुमति होनी चाहिए:
- Google Cloud में, Cloud Pub/Sub API को चालू करें.
- सेवा खाता बनाना में बताए गए तरीके से, सेवा खाता और सेवा खाते की कुंजी बनाएं. हमारा सुझाव है कि आप इसे सिर्फ़ Pub/Sub सदस्य की भूमिका दें. सेवा खाते की कुंजी को उस मशीन पर डाउनलोड करना न भूलें जिस पर Pub/Sub API का इस्तेमाल किया जाएगा.
- पुष्टि करने के लिए अपने क्रेडेंशियल (सेवा खाते की कुंजी) को अपने ऐप्लिकेशन कोड में जोड़ें. इसके लिए, पिछले चरण में दिए गए पेज पर दिए गए निर्देशों का पालन करें. अगर आपको एपीआई ऐक्सेस की तुरंत जांच करनी है, तो
oauth2l
का इस्तेमाल करके मैन्युअल तरीके से ऐक्सेस टोकन पाएं. - मैसेज पाने और उनकी पुष्टि करने के लिए, Pub/Sub
project.subscriptions
एपीआई के साथ सेवा खाते के क्रेडेंशियल या ऐक्सेस टोकन का इस्तेमाल करें.
oauth2l
Google oauth2l
, Go में लिखा गया OAuth के लिए कमांड-लाइन टूल है. इसे Go का इस्तेमाल करके, Mac या Linux के लिए इंस्टॉल करें.
- अगर आपके सिस्टम पर Go नहीं है, तो पहले इसे डाउनलोड और इंस्टॉल करें.
- Go इंस्टॉल होने के बाद,
oauth2l
इंस्टॉल करें और अपनीPATH
एनवायरमेंट वैरिएबल में इसकी जगह जोड़ें:go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
- एपीआई के लिए ऐक्सेस टोकन पाने के लिए,
oauth2l
का इस्तेमाल करें. इसके लिए, सही OAuth स्कोप का इस्तेमाल करें:
उदाहरण के लिए, अगर आपकी सेवा कुंजीoauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub https://www.googleapis.com/auth/cloud-platform
~/myServiceKey-eb0a5f900ee3.json
पर मौजूद है, तो:oauth2l fetch --credentials ~/myServiceKey-eb0a5f900ee3.json --scope https://www.googleapis.com/auth/pubsub https://www.googleapis.com/auth/cloud-platform
ya29.c.Elo4BmHXK5...
इस्तेमाल से जुड़ी ज़्यादा जानकारी के लिए, oauth2l
README देखें.
Google API क्लाइंट लाइब्रेरी
Google API के लिए, OAuth 2.0 का इस्तेमाल करने वाली कई क्लाइंट लाइब्रेरी उपलब्ध हैं. अपनी पसंद की भाषा के बारे में ज़्यादा जानकारी के लिए, Google API क्लाइंट लाइब्रेरी देखें.
Pub/Sub APIके साथ इन लाइब्रेरी का इस्तेमाल करते समय, इन स्कोप स्ट्रिंग का इस्तेमाल करें:
https://www.googleapis.com/auth/pubsub https://www.googleapis.com/auth/cloud-platform
गड़बड़ियां
इस गाइड के बारे में गड़बड़ी के ये कोड दिख सकते हैं:
गड़बड़ी का मैसेज | RPC | समस्या का हल |
---|---|---|
कैमरे की इमेज अब डाउनलोड करने के लिए उपलब्ध नहीं है. | DEADLINE_EXCEEDED |
इवेंट पब्लिश होने के 30 सेकंड बाद, इवेंट की इमेज दिखना बंद हो जाती हैं. समयसीमा खत्म होने से पहले, इमेज डाउनलोड कर लें. |
इवेंट आईडी, कैमरे से जुड़ा नहीं है. | FAILED_PRECONDITION |
कैमरा इवेंट से मिले सही eventID का इस्तेमाल करें. |
एपीआई से जुड़ी गड़बड़ियों के कोड की पूरी सूची के लिए, एपीआई से जुड़ी गड़बड़ी के कोड का रेफ़रंस देखें.