इवेंट

इवेंट एसिंक्रोनस होते हैं और इन्हें 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 आईडी से जुड़ा विषय दिया जाता था. यह विषय इस तरह से दिया जाता था:

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

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

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

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

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

इवेंट का क्रम

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

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

यूज़र आईडी

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

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

मिलते-जुलते इवेंट

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

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

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

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

{
  "eventId" : "8dacc556-0a2d-4aae-9f37-cc349e4a9b0d",
  "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 का अब संबंध है. ऊपर दिए गए उदाहरण में, a user ने इस डिवाइस का ऐक्सेस a 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"
}

रिलेशन इवेंट इन स्थितियों में नहीं भेजे जाते:

• किसी रूम को मिटाया गया हो

संसाधन इवेंट

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

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

{
  "eventId" : "10be3773-cb91-4472-a6c2-501c8d970679",
  "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" : "80cafb5d-d514-4d6b-941f-07f38d0cf9d1",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "liFUn_ajKYEsJy5W3fYtImPyEF...",
      }
    }
  }
  "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 विषय पर पब्लिश करने से फ़िल्टर किया जा सकता है. इस तरीके को इवेंट फ़िल्टरिंग कहा जाता है. इवेंट फ़िल्टर करने का मकसद, कम समय में एक जैसे कई इवेंट मैसेज पब्लिश करने से बचना है.

उदाहरण के लिए, किसी शुरुआती मोशन इवेंट के लिए, SDM विषय पर कोई मैसेज पब्लिश किया जा सकता है. इसके बाद, 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 सदस्य की भूमिका दें. पक्का करें कि आपने सेवा खाते की कुंजी को उस मशीन पर डाउनलोड किया हो जो Pub/Sub API का इस्तेमाल करेगी.
3. पिछले चरण में दिए गए पेज पर मौजूद निर्देशों का पालन करके, अपने ऐप्लिकेशन कोड को पुष्टि करने के क्रेडेंशियल (सेवा खाते की कुंजी) दें. इसके अलावा, अगर आपको एपीआई ऐक्सेस की तुरंत जांच करनी है, तो oauth2l का इस्तेमाल करके, मैन्युअल तरीके से ऐक्सेस टोकन पाएं.
4. संदेशों को पुल करने और उनकी पुष्टि करने के लिए, सेवा खाते के क्रेडेंशियल या ऐक्सेस टोकन का इस्तेमाल Pub/Sub project.subscriptions API के साथ करें.

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. सही 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 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

गड़बड़ियां

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

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