इवेंट

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

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

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

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

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

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

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

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

उदाहरण के लिए, क्विक स्टार्ट गाइड में Authorize पेज देखें.

इवेंट का क्रम

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

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

यूज़र आईडी

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

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

रिलेशन इवेंट

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

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

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

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

{
  "eventId" : "c873a147-2a89-40ed-8ccb-68e8475430e1",
  "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" : "16e90a37-d13b-4057-857b-127273cf9447",
  "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" : "f23283c6-968a-48c0-a92e-415577715b0e",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "V1y7sbSe1Bc_1aaJPwuk_qqpzU...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

फ़ील्ड

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

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

चुनिंदा इवेंट के लिए, अपडेट की जा सकने वाली सूचनाएं पाने की सुविधा उपलब्ध है. साथ ही, दस्तावेज़ में उन्हें इस तरह टैग किया गया है: अपडेट की जा सकने वाली सूचनाएं  . इन इवेंट के पेलोड में, 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 API के साथ करें.

oauth2l

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

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

गड़बड़ियां

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

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