इवेंट

इवेंट एसिंक्रोनस होते हैं. इन्हें 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 की अनुमतियां अमान्य नहीं होती हैं. खुद से होस्ट किए गए विषयों और सदस्यताओं पर, standard Google Cloud Pub/Sub pricing की सामान्य कीमत लागू होती है. इसमें हर महीने 10 जीबी का मुफ़्त टियर शामिल है. ज़्यादा जानकारी के लिए, विषय बनाना लेख पढ़ें.

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

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

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

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

इवेंट का क्रम

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

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

यूज़र आईडी

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

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

रिलेशन इवेंट

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

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

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

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

{
  "eventId" : "768e4eea-b61d-428b-8926-c67e2abaddf9",
  "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" : "ae3f760e-9e1f-4c14-b911-28482e86e56d",
  "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 ऑब्जेक्ट के साथ पेलोड भी होता है. हालांकि, इसमें events ऑब्जेक्ट के बजाय traits ऑब्जेक्ट होता है:

{
  "eventId" : "aecdfca3-25ec-4738-bdbf-d24c4a209d93",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "jE1ZfUIAp6z2anjwTJp5E8QxvC...",
      }
    }
  }
  "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 के लिए, सेवा खाते की अनुमति देने के लिए, Two-legged 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. एपीआई के लिए ऐक्सेस टोकन पाने के लिए, 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 APIs के लिए कई क्लाइंट लाइब्रेरी उपलब्ध हैं. इनमें OAuth 2.0 का इस्तेमाल किया जाता है. अपनी पसंद की भाषा के बारे में ज़्यादा जानने के लिए, Google API की क्लाइंट लाइब्रेरी देखें.

Pub/Sub APIके साथ इन लाइब्रेरी का इस्तेमाल करते समय, ये स्कोप स्ट्रिंग इस्तेमाल करें:

https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

गड़बड़ियां

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

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