इवेंट

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

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

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

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 API कॉल को एक बार ट्रिगर करें. इस कॉल के बाद, सभी स्ट्रक्चर और डिवाइसों के लिए इवेंट पब्लिश किए जाएंगे.

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

इवेंट का क्रम

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

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

यूज़र आईडी

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

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

रिलेशन इवेंट

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

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

• CREATED
• DELETED
• UPDATED

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

{
  "eventId" : "904c338e-7c6c-47e9-99be-7b658c422d0e",
  "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 developeruser

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" : "a95d10a9-8319-4ed0-907b-71574bffad61",
  "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"
  ]
}

किसी भी ट्रेट फ़ील्ड में बदलाव वाले संसाधन इवेंट के पेलोड फ़ॉर्मैट को समझने के लिए, हर ट्रेट का दस्तावेज़ देखें.

किसी डिवाइस ऐक्शन के जवाब में जनरेट होने वाले इवेंट में भी पेलोड होता है. इससे ट्रेट फ़ील्ड में कोई बदलाव नहीं होता. हालांकि, इसमें traits ऑब्जेक्ट के बजाय resourceUpdate ऑब्जेक्ट के साथ events ऑब्जेक्ट होता है:

{
  "eventId" : "20aa9878-6dbd-4de4-9a6d-07e749e3f497",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "-NM0xCrbLkZ0E9VCRk0ndIUvN6...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

फ़ील्ड

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

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

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

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

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

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

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

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

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

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

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

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

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

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

हर तरह के इवेंट के लिए, इवेंट फ़िल्टर करने का अपना लॉजिक होता है. इसे 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

गड़बड़ियां

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

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