इवेंट

इवेंट एसिंक्रोनस होते हैं और इन्हें Google Cloud Pub/Sub मैनेज करता है. हर Projectके लिए एक विषय होता है. इवेंट, सभी डिवाइसों और स्ट्रक्चर के लिए अपडेट उपलब्ध कराते हैं. साथ ही, इवेंट की जानकारी तब तक मिलती रहती है, जब तक उपयोगकर्ता ऐक्सेस टोकन को वापस नहीं ले लेता और इवेंट के मैसेज की समयसीमा खत्म नहीं हो जाती.

इवेंट सक्षम करें

SDM API में इवेंट की सुविधा का इस्तेमाल करना ज़रूरी नहीं है. इन्हें चालू करने का तरीका जानने के लिए, इवेंट चालू करें देखें Project.

Google Cloud Pub/Sub

Pub/Sub के काम करने के तरीके के बारे में ज़्यादा जानने के लिए, Google Cloud Pub/Sub का दस्तावेज़ देखें. खास तौर पर:

• Pub/Sub के बारे में बुनियादी जानकारी पाने के लिए, इस्तेमाल करने का तरीका देखें.
• जानें कि पुष्टि करने की प्रोसेस कैसे काम करती है.
• उपलब्ध कराई गई क्लाइंट लाइब्रेरी में से कोई एक चुनें या अपनी लाइब्रेरी बनाएं. इसके बाद, REST/HTTP या gRPC API प्लैटफ़ॉर्म का इस्तेमाल करें.

इवेंट की सदस्यता

जनवरी 2025 से पहले, अगर आपके Projectके लिए इवेंट चालू थे, तो आपको उस Project आईडी के लिए, Google से होस्ट किए गए विषय की जानकारी इस फ़ॉर्मैट में दी गई होगी:

projects/sdm-prod/topics/enterprise-project-id

अब सभी प्रोजेक्ट को अपने Google Cloud प्रोजेक्ट में, Pub/Sub विषयों को खुद होस्ट करना होगा. जनवरी 2025 से, नए प्रोजेक्ट के लिए यह ज़रूरी है. साथ ही, सभी मौजूदा प्रोजेक्ट के लिए 30 नवंबर, 2026 तक ऐसा करना ज़रूरी है. इसके लिए, इस फ़ॉर्मैट का इस्तेमाल करें:

projects/gcp-project-name/subscriptions/topic-id

अगर आपके project में पहले से ही, आपके Google Cloud प्रोजेक्ट में खुद होस्ट किया गया विषय इस्तेमाल किया जा रहा है, तो आपको कुछ करने की ज़रूरत नहीं है. Pub/Sub विषय के कॉन्फ़िगरेशन को माइग्रेट करने से, उपयोगकर्ता के मौजूदा ऐक्सेस टोकन या OAuth की अनुमतियां अमान्य नहीं होती हैं. खुद होस्ट किए गए विषयों और सदस्यताओं पर, Google Cloud Pub/Sub की स्टैंडर्ड कीमत लागू होती है. इसमें हर महीने 10 जीबी का मुफ़्त टियर शामिल है. ज़्यादा जानकारी के लिए, कोई विषय बनाना लेख पढ़ें.

इवेंट पाने के लिए, उस विषय के लिए पुल या पुश सदस्यता बनाएं. यह आपके इस्तेमाल के उदाहरण पर निर्भर करता है. एसडीएम विषय की कई सदस्यताएं ली जा सकती हैं. ज़्यादा जानकारी के लिए, सदस्यताएं मैनेज करना देखें.

इवेंट शुरू करना

Pub/Sub सदस्यता बनाने के बाद, पहली बार इवेंट शुरू करने के लिए, एक बार ट्रिगर होने वाले devices.list एपीआई कॉल करें. इस कॉल के बाद, सभी स्ट्रक्चर और डिवाइसों के इवेंट पब्लिश किए जाएंगे.

उदाहरण के लिए, आसानी से बताने/सिखाने वाली गाइड में अनुमति दें पेज देखें.

इवेंट का क्रम

Pub/Sub, इवेंट की डिलीवरी के क्रम की गारंटी नहीं देता. साथ ही, इवेंट मिलने का क्रम, इवेंट के असल क्रम से अलग हो सकता है. इवेंट के क्रम का मिलान करने के लिए, timestamp फ़ील्ड का इस्तेमाल करें. इवेंट अलग-अलग या एक साथ, एक ही इवेंट मैसेज में भी मिल सकते हैं.

ज़्यादा जानकारी के लिए, मैसेज का क्रम देखें.

यूज़र आईडी

अगर आपका सेटअप, स्ट्रक्चर या डिवाइस के बजाय उपयोगकर्ताओं पर आधारित है, तो संसाधनों और इवेंट को आपस में जोड़ने के लिए, इवेंट पेलोड के userID फ़ील्ड का इस्तेमाल करें. यह फ़ील्ड, किसी उपयोगकर्ता को दिखाने वाला एक छिपा हुआ आईडी होता है.

userID, हर एपीआई कॉल के एचटीटीपी रिस्पॉन्स हेडर में भी उपलब्ध होता है.

रिलेशन इवेंट

रिलेशन इवेंट, किसी संसाधन के लिए रिलेशन से जुड़े अपडेट को दिखाते हैं. उदाहरण के लिए, किसी डिवाइस को स्ट्रक्चर में जोड़ने या उससे हटाने पर.

रिलेशन इवेंट तीन तरह के होते हैं:

• CREATED
• हटा दिया गया
• अपडेट कर दिया गया है

रिलेशन इवेंट का पेलोड इस तरह होता है:

{
  "eventId" : "7c786f36-8068-4b86-ba67-d6e0d28ebb11",
  "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 हमेशा खाली रहता है.

फ़ील्ड

अलग-अलग तरह के इवेंट और उनके काम करने के तरीके के बारे में ज़्यादा जानने के लिए, इवेंट देखें.

उदाहरण

रिलेशन इवेंट के हर टाइप के लिए, इवेंट पेलोड अलग-अलग होते हैं:

"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"
}

रिलेशन इवेंट तब नहीं भेजे जाते, जब:

• कोई चैट रूम मिटाया जाता है

संसाधन से जुड़े इवेंट

संसाधन इवेंट, किसी संसाधन से जुड़े अपडेट को दिखाता है. यह किसी विशेषता वाले फ़ील्ड की वैल्यू में हुए बदलाव के जवाब में हो सकता है. जैसे, थर्मोस्टैट का मोड बदलना. यह किसी डिवाइस के ऐसे ऐक्शन को भी दिखा सकता है जिससे किसी ट्रेट फ़ील्ड में बदलाव नहीं होता. जैसे, डिवाइस का बटन दबाना.

ट्रेट फ़ील्ड की वैल्यू में बदलाव होने पर जनरेट होने वाले इवेंट में, traits ऑब्जेक्ट शामिल होता है. यह डिवाइस के GET कॉल जैसा ही होता है:

{
  "eventId" : "59381967-62e1-427b-98b8-67d5dbbd590c",
  "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" : "1608503f-fedf-43cc-b29c-aa4e3b685a60",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "Ki0F7T-Joca_uRg42loDugGevl...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

इस तरह के रिसॉर्स इवेंट, खास ट्रेट में तय किए जाते हैं. उदाहरण के लिए, मोशन इवेंट को CameraMotion trait में तय किया गया है. इस तरह के रिसॉर्स इवेंट के लिए पेलोड फ़ॉर्मैट को समझने के लिए, हर विशेषता का दस्तावेज़ देखें.

फ़ील्ड

अलग-अलग तरह के इवेंट और उनके काम करने के तरीके के बारे में ज़्यादा जानने के लिए, इवेंट देखें.

अपडेट की जा सकने वाली सूचनाएं

चुनिंदा इवेंट के लिए, अपडेट की जा सकने वाली सूचनाएं पाने की सुविधा उपलब्ध है. दस्तावेज़ में इन्हें अपडेट की जा सकने वाली सूचनाएं  के तौर पर टैग किया गया है. इन इवेंट के पेलोड में, eventThreadId नाम का एक अतिरिक्त फ़ील्ड होता है. इस फ़ील्ड का इस्तेमाल, अलग-अलग इवेंट को एक साथ लिंक करने के लिए करें. ऐसा किसी उपयोगकर्ता को दिखाई गई मौजूदा सूचना को अपडेट करने के लिए किया जाता है.

इवेंट थ्रेड और इवेंट सेशन में अंतर होता है. इवेंट थ्रेड से, एक ही थ्रेड में मौजूद पिछले इवेंट की अपडेट की गई स्थिति का पता चलता है. इवेंट सेशन, एक-दूसरे से जुड़े अलग-अलग इवेंट की पहचान करता है. साथ ही, किसी इवेंट सेशन के लिए कई इवेंट थ्रेड हो सकते हैं.

सूचना देने के लिए, अलग-अलग तरह के इवेंट को अलग-अलग थ्रेड में बांटा जाता है.

थ्रेड को ग्रुप करने और टाइमिंग के लॉजिक को Google मैनेज करता है. इसमें कभी भी बदलाव किया जा सकता है. SDM API से मिले इवेंट थ्रेड और सेशन के आधार पर, A developer को सूचनाएं अपडेट करनी चाहिए.

थ्रेड की स्थिति

जिन इवेंट के लिए अपडेट की जा सकने वाली सूचनाएं पाने की सुविधा उपलब्ध होती है उनमें eventThreadState फ़ील्ड भी होता है. इससे पता चलता है कि उस समय इवेंट थ्रेड की स्थिति क्या थी. इस फ़ील्ड में ये वैल्यू होती हैं:

• STARTED — इवेंट थ्रेड का पहला इवेंट.
• अपडेट किया गया — किसी इवेंट थ्रेड में मौजूद इवेंट. एक थ्रेड में, इस स्थिति वाले इवेंट की संख्या शून्य या इससे ज़्यादा हो सकती है.
• ENDED — यह इवेंट थ्रेड का आखिरी इवेंट होता है. यह UPDATED इवेंट का डुप्लीकेट हो सकता है. हालांकि, यह थ्रेड के टाइप पर निर्भर करता है.

इस फ़ील्ड का इस्तेमाल, किसी इवेंट थ्रेड की प्रोग्रेस और उसके खत्म होने का समय ट्रैक करने के लिए किया जा सकता है.

इवेंट फ़िल्टर करना

कुछ मामलों में, ऐसा हो सकता है कि किसी डिवाइस से डिटेक्ट किए गए इवेंट, SDM Pub/Sub विषय पर पब्लिश न किए जाएं. इस प्रोसेस को इवेंट फ़िल्टर करना कहते हैं. इवेंट फ़िल्टर करने का मकसद, कम समय में एक जैसे कई इवेंट मैसेज पब्लिश करने से बचना है.

उदाहरण के लिए, किसी शुरुआती मोशन इवेंट के लिए, एसडीएम विषय पर कोई मैसेज पब्लिश किया जा सकता है. इसके बाद, Motion के लिए भेजे गए अन्य मैसेज, तय समय तक पब्लिश नहीं किए जाएंगे. यह अवधि खत्म होने के बाद, उस इवेंट टाइप के लिए इवेंट मैसेज फिर से पब्लिश किया जा सकता है.

Google Home ऐप्लिकेशन (GHA) में, फ़िल्टर किए गए इवेंट अब भी userकी गतिविधियों की वीडियो रिकॉर्डिंग के इतिहास में दिखेंगे. हालांकि, इस तरह के इवेंट के लिए ऐप्लिकेशन की सूचना जनरेट नहीं होती. भले ही, उस तरह की सूचना पाने की सुविधा चालू हो.

हर तरह के इवेंट के लिए, इवेंट फ़िल्टर करने का अपना लॉजिक होता है. इसे Google तय करता है और इसमें कभी भी बदलाव किया जा सकता है. इवेंट को फ़िल्टर करने का यह लॉजिक, इवेंट थ्रेड और सेशन लॉजिक से अलग होता है.

सेवा खाते

SDM API की सदस्यताएं और इवेंट मैसेज मैनेज करने के लिए, सेवा खातों का इस्तेमाल करने का सुझाव दिया जाता है. सेवा खाते का इस्तेमाल किसी ऐप्लिकेशन या वर्चुअल मशीन के लिए किया जाता है, न कि किसी व्यक्ति के लिए. साथ ही, इसके पास अपनी यूनीक खाता कुंजी होती है.

Pub/Sub API के लिए सेवा खाते की अनुमति, दो लेग वाले OAuth (2LO) का इस्तेमाल करती है.

2LO ऑथराइज़ेशन फ़्लो में:

• developer , सेवा कुंजी का इस्तेमाल करके ऐक्सेस टोकन का अनुरोध करता है.
• developer , एपीआई को किए जाने वाले कॉल के साथ ऐक्सेस टोकन का इस्तेमाल करता है.

Google 2LO और इसे सेट अप करने के तरीके के बारे में ज़्यादा जानने के लिए, सर्वर से सर्वर ऐप्लिकेशन के लिए OAuth 2.0 का इस्तेमाल करना लेख पढ़ें.

अनुमति देना

सेवा खाते को Pub/Sub API के साथ इस्तेमाल करने की अनुमति होनी चाहिए:

1. Google Cloud में, Cloud Pub/Sub API चालू करें.
2. सेवा खाता बनाना लेख में दिए गए निर्देशों के मुताबिक, सेवा खाता और सेवा खाता कुंजी बनाएं. हमारा सुझाव है कि इसे सिर्फ़ Pub/Sub Subscriber की भूमिका दें. सेवा खाते की कुंजी को उस मशीन पर डाउनलोड करना न भूलें जो Pub/Sub API का इस्तेमाल करेगी.
3. पिछले चरण में दिए गए पेज पर मौजूद निर्देशों का पालन करके, अपने ऐप्लिकेशन कोड को पुष्टि करने के क्रेडेंशियल (सेवा खाते की कुंजी) दें. इसके अलावा, अगर आपको एपीआई ऐक्सेस की तुरंत जांच करनी है, तो oauth2l का इस्तेमाल करके, मैन्युअल तरीके से ऐक्सेस टोकन पाएं.
4. मैसेज पाने और उनकी पुष्टि करने के लिए, सेवा खाते के क्रेडेंशियल या ऐक्सेस टोकन का इस्तेमाल करें. इसके लिए, Pub/Sub project.subscriptions एपीआई का इस्तेमाल करें.

oauth2l

Google oauth2l, OAuth के लिए एक कमांड लाइन टूल है. इसे Go में लिखा गया है. इसे Mac या Linux के लिए Go का इस्तेमाल करके इंस्टॉल करें.

1. अगर आपके सिस्टम पर Go नहीं है, तो इसे पहले डाउनलोड और इंस्टॉल करें.
2. Go इंस्टॉल करने के बाद, oauth2l इंस्टॉल करें और इसकी जगह की जानकारी को अपने PATH एनवायरमेंट वैरिएबल में जोड़ें:

   go install github.com/google/oauth2l@latest
   export PATH=$PATH:~/go/bin

3. एपीआई के लिए ऐक्सेस टोकन पाने के लिए, 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

गड़बड़ियां

इस गाइड से जुड़ी गड़बड़ी के ये कोड दिख सकते हैं:

एपीआई के गड़बड़ी कोड की पूरी सूची के लिए, एपीआई के गड़बड़ी कोड का रेफ़रंस देखें.