इवेंट

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

ध्यान दें: अगर आपका Device Access इंटिग्रेशन, Pub/Sub इवेंट पर निर्भर करता है और यह कभी-कभार ही एपीआई कॉल करता है, तो userकी अनुमति वापस ले ली जाएगी, अगर रीफ़्रेश टोकन की समयसीमा खत्म हो जाती है. ऐक्सेस जारी रखने के लिए, आपको 6 महीने के अंदर ऐक्सेस टोकन को रीफ़्रेश करने के लिए, रीफ़्रेश टोकन का इस्तेमाल करना होगा. अनुमति से जुड़ी ज़्यादा मदद पाने के लिए, रीफ़्रेश टोकन की समयसीमा खत्म होना लेख देखें.

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

इवेंट, 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

जनवरी 2025 के बाद बनाए गए प्रोजेक्ट के लिए, Pub/Sub के विषयों को खुद होस्ट करना होगा. साथ ही, आपको अपना विषय आईडी देना होगा. ज़्यादा जानकारी के लिए, विषय बनाना लेख देखें.

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

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

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

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

इवेंट का क्रम

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

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

यूज़र आईडी

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

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

रिलेशन इवेंट

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

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

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

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

पेलोड

{
  "eventId" : "6020f8dc-cf16-4070-9793-3a74e297b296",
  "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 ने इस खास डिवाइस को ऐक्सेस करने की अनुमति दी है. साथ ही, developerका अनुमति वाला डिवाइस अब उनके अनुमति वाले user's स्ट्रक्चर से जुड़ा है. इससे इवेंट ट्रिगर होता है.

subject सिर्फ़ कोई कमरा या स्ट्रक्चर हो सकता है. अगर a developer के पास के user' स्ट्रक्चर को देखने की अनुमति नहीं है, तो subject हमेशा खाली होता है.

फ़ील्ड

फ़ील्ड	ब्यौरा	डेटा टाइप
`eventId`	इवेंट का यूनीक आइडेंटिफ़ायर.	`string` Example: "808d1a1e-063f-4901-8ff8-2004c595cce4"
`timestamp`	इवेंट होने का समय.	`string` Example: "2019-01-01T00:00:01Z"
`relationUpdate`	एक ऑब्जेक्ट, जिसमें रिलेशन अपडेट के बारे में जानकारी दी गई है.	`object`
`userId`	एक यूनीक, आईडी, जो उपयोगकर्ता को दिखाता है.	`string` Example: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"

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

उदाहरण

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

CREATED

स्ट्रक्चर बनाया गया

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

UPDATED

डिवाइस को दूसरी जगह ले जाया गया

"relationUpdate" : {
  "type" : "UPDATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

DELETED

स्ट्रक्चर मिटाया गया

"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" : "c0f5f713-ec68-4aed-868d-85eaed6a26e7",
  "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 ऑब्जेक्ट के बजाय events ऑब्जेक्ट के साथ resourceUpdate ऑब्जेक्ट होता है:

पेलोड

{
  "eventId" : "2af57608-415c-4c67-9f66-3edbdf82bf4a",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "_wHEvcpb2sPsNjtMCeDoJx7P1G...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

फ़ील्ड

फ़ील्ड	ब्यौरा	डेटा टाइप
`eventId`	इवेंट का यूनीक आइडेंटिफ़ायर.	`string` Example: "2af57608-415c-4c67-9f66-3edbdf82bf4a"
`timestamp`	इवेंट होने का समय.	`string` Example: "2019-01-01T00:00:01Z"
`resourceUpdate`	एक ऑब्जेक्ट, जिसमें संसाधन अपडेट के बारे में जानकारी दी गई है.	`object`
`userId`	एक यूनीक, आईडी, जो उपयोगकर्ता को दिखाता है.	`string` Example: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
`eventThreadId`	इवेंट थ्रेड का यूनीक आइडेंटिफ़ायर.	`string` Example: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
`eventThreadState`	इवेंट थ्रेड की स्थिति.	`string` Values: "STARTED", "UPDATED", "ENDED"
`resourceGroup`	एक ऑब्जेक्ट, जो उन संसाधनों को दिखाता है जिनके लिए इस इवेंट के जैसे ही अपडेट हो सकते हैं. इवेंट का संसाधन (जो `resourceUpdate` ऑब्जेक्ट से मिलता है) हमेशा इस ऑब्जेक्ट में मौजूद रहेगा.	`object`

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

संसाधन इवेंट के आधार पर सूचनाएं, किसी ऐप्लिकेशन में लागू की जा सकती हैं. जैसे, Android या iOS के लिए. भेजी जाने वाली सूचनाओं की संख्या कम करने के लिए, अपडेट की जा सकने वाली सूचनाएं नाम की सुविधा लागू की जा सकती है. इसमें, एक ही इवेंट थ्रेड में होने वाले अगले इवेंट के आधार पर, मौजूदा सूचनाओं को नई जानकारी के साथ अपडेट किया जाता है.

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

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

oauth2l

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

अगर आपके सिस्टम पर Go नहीं है, तो पहले इसे डाउनलोड और इंस्टॉल करें.
Go इंस्टॉल होने के बाद, oauth2l इंस्टॉल करें और इसकी जगह को अपने PATH एनवायरमेंट वैरिएबल में जोड़ें:
```
go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
```
एपीआई के लिए ऐक्सेस टोकन पाने के लिए, 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

गड़बड़ियां

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

गड़बड़ी का मैसेज	RPC	समस्या का हल
कैमरे की इमेज अब डाउनलोड के लिए उपलब्ध नहीं है.	`DEADLINE_EXCEEDED`	इवेंट पब्लिश होने के 30 सेकंड बाद, इवेंट की इमेज की समयसीमा खत्म हो जाती है. पक्का करें कि आपने समयसीमा खत्म होने से पहले इमेज डाउनलोड कर ली हो.
इवेंट आईडी, कैमरे से जुड़ा नहीं है.	`FAILED_PRECONDITION`	कैमरे के इवेंट से मिले सही `eventID` का इस्तेमाल करें.

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

इवेंट संग्रह की मदद से व्यवस्थित रहें अपनी प्राथमिकताओं के आधार पर, कॉन्टेंट को सेव करें और कैटगरी में बांटें.

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

Google Cloud Pub/Sub

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

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

इवेंट का क्रम

यूज़र आईडी

रिलेशन इवेंट

पेलोड

फ़ील्ड

उदाहरण

CREATED

स्ट्रक्चर बनाया गया

डिवाइस बनाया गया

डिवाइस बनाया गया

UPDATED

डिवाइस को दूसरी जगह ले जाया गया

DELETED

स्ट्रक्चर मिटाया गया

डिवाइस मिटाया गया

डिवाइस मिटाया गया

संसाधन इवेंट

पेलोड

पेलोड

फ़ील्ड

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

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

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

सेवा खाते

अनुमति देना

oauth2l

Google API की क्लाइंट लाइब्रेरी

गड़बड़ियां

इवेंट