इवेंट एसिंक्रोनस होते हैं और इन्हें Google Cloud Pub/Sub के ज़रिए मैनेज किया जाता है. ये इवेंट, एक ही विषय के लिए हर Projectके हिसाब से किए जाते हैं. इवेंट सभी डिवाइसों और स्ट्रक्चर के लिए अपडेट देता है. साथ ही, इवेंट की रसीद तब तक सुरक्षित रहती है, जब तक उपयोगकर्ता ने ऐक्सेस टोकन को रद्द नहीं किया और इवेंट के मैसेज की समयसीमा खत्म न हो गई हो.
इवेंट सक्षम करें
इवेंट, SDM API की वैकल्पिक सुविधा है. अपने Projectके लिए इवेंट चालू करने का तरीका देखें और उन्हें चालू करने का तरीका जानें.
Google Cloud Pub/Sub
Pub/Sub के काम करने के तरीके के बारे में ज़्यादा जानने के लिए, Google Cloud Pub/Sub का दस्तावेज़ देखें. खास तौर पर:
- Pub/Sub की बुनियादी बातों की जानकारी के लिए, इस्तेमाल करने के तरीके की गाइड देखें.
- जानें कि पुष्टि करने की सुविधा कैसे काम करती है.
- दी गई क्लाइंट लाइब्रेरी चुनें या अपनी खुद की क्लाइंट लाइब्रेरी लिखें और REST/HTTP या gRPC API प्लैटफ़ॉर्म का इस्तेमाल करें.
इवेंट की सदस्यता
आपके Projectके लिए इवेंट चालू होने पर, आपको उस Project आईडी से जुड़ा विषय उपलब्ध कराया जाएगा. यह इस तरह होगा:
projects/sdm-prod/topics/enterprise-project-id
इवेंट पाने के लिए, अपने इस्तेमाल के उदाहरण के हिसाब से उस विषय के लिए pull या push की सदस्यता बनाएं. एसडीएम के लिए एक से ज़्यादा सदस्यताएं ली जा सकती हैं. ज़्यादा जानकारी के लिए, सदस्यताएं मैनेज करना देखें.
इवेंट शुरू करें
Pub/Sub सदस्यता बनाने के बाद, पहली बार इवेंट शुरू करने के लिए, एक बार के ट्रिगर के तौर पर
devices.list
एपीआई कॉल करें. इस कॉल के बाद, सभी स्ट्रक्चर और डिवाइसों के इवेंट पब्लिश
हो जाएंगे.
उदाहरण के लिए, आसानी से सिखाने वाली गाइड में, अनुमति दें पेज देखें.
इवेंट का क्रम
Pub/Sub, इवेंट के ऑर्डर किए गए डिलीवरी की गारंटी नहीं देता है. साथ ही, हो सकता है कि इवेंट की रसीद का क्रम, उस क्रम के मुताबिक न हो जिसमें इवेंट असल में हुए थे. इवेंट के ऑर्डर से जुड़ी समस्या को हल करने के लिए, timestamp
फ़ील्ड का इस्तेमाल करें. इवेंट अलग-अलग या एक साथ एक इवेंट मैसेज में भी आ सकते हैं.
ज़्यादा जानकारी के लिए, मैसेज का ऑर्डर देना देखें.
यूज़र आईडी
अगर आपका फ़ंक्शन, स्ट्रक्चर या डिवाइस के बजाय उपयोगकर्ताओं के हिसाब से है, तो रिसॉर्स और इवेंट को जोड़ने के लिए, इवेंट पेलोड के userID
फ़ील्ड का इस्तेमाल करें. यह फ़ील्ड एक अस्पष्ट आईडी है, जो खास उपयोगकर्ता को दिखाता है.
हर एपीआई कॉल के एचटीटीपी रिस्पॉन्स हेडर में userID
भी उपलब्ध होता है.
रिलेशन इवेंट
रिलेशन इवेंट, किसी संसाधन से जुड़े अपडेट को दिखाते हैं. उदाहरण के लिए, जब किसी डिवाइस को किसी स्ट्रक्चर में जोड़ा जाता है या जब किसी डिवाइस को स्ट्रक्चर से मिटाया जाता है.
रिलेशन इवेंट तीन तरह के होते हैं:
- बनाया गया
- हटा दिया गया
- अपडेट कर दिया गया है
किसी रिलेशन इवेंट के लिए पेलोड इस तरह का है:
पेलोड
{ "eventId" : "eed9763a-8735-45d9-81d9-e0621c130eb1", "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 उदाहरण के लिए: "1362476b-4ac4-4608-a8be-4c8cf4101426" |
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" }
रिलेशन इवेंट नहीं भेजे जाते, जब:
- एक कमरा मिटाया गया है
संसाधन इवेंट
संसाधन इवेंट, किसी संसाधन के लिए खास अपडेट दिखाता है. ऐसा trait फ़ील्ड की वैल्यू में बदलाव होने पर किया जा सकता है. जैसे, थर्मोस्टैट का मोड बदलना. यह किसी ऐसे डिवाइस ऐक्शन को भी दिखा सकता है जिससे Trait फ़ील्ड में कोई बदलाव नहीं होता. जैसे, डिवाइस बटन दबाना.
Trait फ़ील्ड की वैल्यू में बदलाव होने पर जनरेट किए गए इवेंट में,
traits
ऑब्जेक्ट मौजूद होता है. यह ऑब्जेक्ट, डिवाइस के जीईटी कॉल से मिलता-जुलता होता है:
पेलोड
{
"eventId" : "5b98a768-6771-4d4d-836d-58cce3a62cca",
"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"
]
}
trait फ़ील्ड में बदलाव से जुड़े किसी भी संसाधन इवेंट के पेलोड फ़ॉर्मैट को समझने के लिए, अलग-अलग Trait के दस्तावेज़ इस्तेमाल करें.
डिवाइस पर की गई कार्रवाई के जवाब में जनरेट किए गए ऐसे इवेंट जो किसी Trait फ़ील्ड में बदलाव नहीं करते, उनमें भी resourceUpdate
ऑब्जेक्ट वाला पेलोड होता है. हालांकि, इसमें traits
ऑब्जेक्ट के बजाय events
ऑब्जेक्ट होता है:
पेलोड
{ "eventId" : "3426d266-406b-48f3-9595-5192229a39a0",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion
" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "8XZ1cQ76Becovj551YfM9ZnuwB...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }
इस तरह के संसाधन इवेंट की खास बातें होती हैं. उदाहरण के लिए, मोशन इवेंट की जानकारी CameraMotion एट्रिब्यूट में दी जाती है. इस तरह के संसाधन इवेंट के पेलोड फ़ॉर्मैट को समझने के लिए, हर Trait के दस्तावेज़ देखें.
फ़ील्ड
फ़ील्ड | ब्यौरा | डेटा टाइप |
---|---|---|
eventId |
इवेंट के लिए यूनीक आइडेंटिफ़ायर. | string जैसे: "3426d266-406b-48f3-9595-5192229a39a0" |
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 मैनेज करता है. इसे किसी भी समय बदला जा सकता है. A developer को, SDM API से मिले इवेंट थ्रेड और सेशन के हिसाब से सूचनाएं अपडेट करनी चाहिए.
थ्रेड की स्थिति
जिन इवेंट में अपडेट की जा सकने वाली सूचनाएं काम करती हैं उनमें एक eventThreadState
फ़ील्ड भी होता है, जो उस समय इवेंट थ्रेड की स्थिति के बारे में बताता है. इस फ़ील्ड में ये वैल्यू हैं:
- शुरू किया गया — किसी इवेंट थ्रेड में पहला इवेंट.
- अपडेट किया गया — मौजूदा इवेंट थ्रेड में कोई इवेंट. किसी एक थ्रेड में इस स्थिति वाले इवेंट की संख्या शून्य या उससे ज़्यादा हो सकती है.
- खत्म हो गया — इवेंट थ्रेड में आखिरी इवेंट, जो थ्रेड के टाइप के आधार पर, पिछले अपडेट किए गए इवेंट का डुप्लीकेट हो सकता है.
इस फ़ील्ड का इस्तेमाल, किसी इवेंट थ्रेड की प्रोग्रेस और उसके खत्म होने की तारीख को ट्रैक करने के लिए किया जा सकता है.
इवेंट फ़िल्टर करना
कुछ मामलों में, डिवाइस के ज़रिए पता लगाए गए इवेंट को SDM Pub/Sub विषय में पब्लिश करने से फ़िल्टर करके बाहर किया जा सकता है. इस व्यवहार को इवेंट फ़िल्टर करना कहा जाता है. इवेंट को फ़िल्टर करने का मकसद, कम समय में एक जैसे कई इवेंट मैसेज पब्लिश होने से रोकना है.
उदाहरण के लिए, शुरुआती मोशन इवेंट के लिए एसडीएम के विषय में कोई मैसेज पब्लिश किया जा सकता है. इसके बाद, मोशन से जुड़े दूसरे मैसेज, तय समयसीमा के अंदर पब्लिश होने से फ़िल्टर कर दिए जाएंगे. यह समयसीमा खत्म होने के बाद, उस तरह के इवेंट के लिए मैसेज फिर से पब्लिश किया जा सकता है.
Google Home ऐप्लिकेशन (जीएचए) में, फ़िल्टर किए गए इवेंट userके इवेंट इतिहास में अब भी दिखेंगे. हालांकि, ऐसे इवेंट से ऐप्लिकेशन से जुड़ी कोई सूचना जनरेट नहीं होती (भले ही, उस तरह की सूचना चालू हो).
हर तरह के इवेंट का अपना इवेंट फ़िल्टर करने का लॉजिक होता है. यह Google तय करता है और इसे किसी भी समय बदला जा सकता है. इवेंट को फ़िल्टर करने का यह लॉजिक, इवेंट थ्रेड और सेशन लॉजिक से अलग है.
सेवा वाले खाते
SDM API की सदस्यताओं और इवेंट मैसेज को मैनेज करने के लिए, सेवा खातों का सुझाव दिया जाता है. सेवा खाते का इस्तेमाल कोई ऐप्लिकेशन या वर्चुअल मशीन करता है, न कि कोई व्यक्ति. साथ ही, उसके पास अपनी यूनीक खाता कुंजी होती है.
Pub/Sub एपीआई के लिए सेवा खाते की अनुमति देने के लिए, दो पैरों वाले OAuth (2LO) का इस्तेमाल किया जाता है.
2LO की अनुमति देने वाले फ़्लो में:
- developer , सर्विस कुंजी का इस्तेमाल करके ऐक्सेस टोकन का अनुरोध करता है.
- developer , एपीआई को कॉल करने के साथ ऐक्सेस टोकन का इस्तेमाल करता है.
Google 2LO के बारे में ज़्यादा जानने और इसे सेट अप करने के तरीके के बारे में जानने के लिए, सर्वर से सर्वर ऐप्लिकेशन के लिए OAuth 2.0 का इस्तेमाल करना देखें.
अनुमति
सेवा खाते के पास Pub/Sub API के साथ इस्तेमाल करने की अनुमति होनी चाहिए:
- Google Cloud में, Cloud Pub/Sub एपीआई चालू करें.
- सेवा खाता बनाने में बताए गए तरीके से सेवा खाता और सेवा खाता कुंजी बनाएं. हमारा सुझाव है कि आप इसे सिर्फ़ Pub/Sub के सदस्य की भूमिका दें. पक्का करें कि सेवा खाता कुंजी को उस मशीन पर डाउनलोड किया गया हो जो Pub/Sub API का इस्तेमाल करेगी.
- पिछले चरण में दिए गए पेज पर दिए गए निर्देशों का पालन करके, अपने ऐप्लिकेशन कोड में पुष्टि करने के लिए क्रेडेंशियल (सेवा खाता कुंजी) दें या अगर आपको एपीआई ऐक्सेस को फटाफट टेस्ट करना है, तो
oauth2l
का इस्तेमाल करके मैन्युअल तरीके से ऐक्सेस टोकन पाएं. - मैसेज पाने और उन्हें स्वीकार करने के लिए, Pub/Sub
project.subscriptions
एपीआई के साथ सेवा खाते के क्रेडेंशियल या ऐक्सेस टोकन का इस्तेमाल करें.
Oauth2l
Google oauth2l
, Go में लिखे गए OAuth के लिए एक कमांड लाइन टूल है. इसे Mac या Linux के लिए इंस्टॉल करें.
- अगर आपके सिस्टम पर Go नहीं है, तो पहले इसे डाउनलोड और इंस्टॉल करें.
- Go इंस्टॉल होने के बाद,
oauth2l
को इंस्टॉल करें और इसकी जगह को अपनेPATH
के एनवायरमेंट वैरिएबल में जोड़ें:go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
- सही OAuth दायरे का इस्तेमाल करके, एपीआई के लिए ऐक्सेस टोकन पाने के लिए
oauth2l
का इस्तेमाल करें:
उदाहरण के लिए, अगर आपकी सेवा कुंजी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
पढ़ें.
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 का इस्तेमाल करें. |
एपीआई से जुड़े गड़बड़ी कोड की पूरी सूची देखने के लिए, एपीआई से जुड़े गड़बड़ी कोड का रेफ़रंस देखें.