इवेंट

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

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

इवेंट, SDM API की एक वैकल्पिक सुविधा है. इवेंट चालू करें देखें और जानें कि उन्हें अपने Projectके लिए कैसे चालू करें.

Google Cloud Pub/Sub

Pub/Sub के काम करने के तरीके के बारे में ज़्यादा जानने के लिए, Google Cloud Pub/Sub का दस्तावेज़ देखें. खास तौर पर:

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

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

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

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

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

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

इवेंट का क्रम

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

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

यूज़र आईडी

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

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

रिलेशन इवेंट

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

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

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

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

पेलोड

{
  "eventId" : "1a2e13bc-c23c-4bc4-8366-6b5669607f0e",
  "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 हमेशा खाली रहता है.

फ़ील्ड

फ़ील्ड ब्यौरा डेटा टाइप
eventId इवेंट के लिए यूनीक आइडेंटिफ़ायर. string
उदाहरण: "a121b435-e3bb-4ba1-9dea-945686b7dabf"
timestamp इवेंट होने का समय. string
उदाहरण: "2019-01-01T00:00:01Z"
relationUpdate ऐसा ऑब्जेक्ट जिसमें संबंध के अपडेट के बारे में जानकारी होती है. object
userId यह एक यूनीक और छिपा हुआ आइडेंटिफ़ायर होता है, जो उपयोगकर्ता को दिखाता है. string
उदाहरण: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"

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

उदाहरण

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

बनाया गया

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

"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" : "caec1000-1cab-43d3-946f-bc3c5f8615c9",
  "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"
  ]
}

किसी भी trait field change resource event के लिए पेलोड फ़ॉर्मैट को समझने के लिए, trait documentation का इस्तेमाल करें.

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

पेलोड

{
  "eventId" : "0111d3f2-5e7d-4ecf-88ed-8f3b0324f75c",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "jOvQqNOSL76837k_JxTR4BJ6nw...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

फ़ील्ड

फ़ील्ड ब्यौरा डेटा टाइप
eventId इवेंट के लिए यूनीक आइडेंटिफ़ायर. string
उदाहरण: "0111d3f2-5e7d-4ecf-88ed-8f3b0324f75c"
timestamp इवेंट होने का समय. string
उदाहरण: "2019-01-01T00:00:01Z"
resourceUpdate ऐसा ऑब्जेक्ट जिसमें संसाधन के अपडेट के बारे में जानकारी होती है. object
userId यह एक यूनीक और छिपा हुआ आइडेंटिफ़ायर होता है, जो उपयोगकर्ता को दिखाता है. string
उदाहरण: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
eventThreadId इवेंट थ्रेड के लिए यूनीक आइडेंटिफ़ायर. string
उदाहरण: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
eventThreadState इवेंट थ्रेड की स्थिति. string
वैल्यू: "STARTED", "UPDATED", "ENDED"
resourceGroup ऐसा ऑब्जेक्ट जो उन संसाधनों के बारे में बताता है जिनमें इस इवेंट से मिलते-जुलते अपडेट हो सकते हैं. इवेंट का संसाधन (resourceUpdate ऑब्जेक्ट से) हमेशा इस ऑब्जेक्ट में मौजूद रहेगा. object

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

हर तरह के इवेंट के लिए, इवेंट फ़िल्टर करने का अपना लॉजिक होता है. इसे Google तय करता है और इसमें कभी भी बदलाव किया जा सकता है. इवेंट को फ़िल्टर करने का यह लॉजिक, इवेंट थ्रेड और सेशन लॉजिक से अलग होता है.

सेवा खाते

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

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 एपीआई का इस्तेमाल करें.

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. एपीआई के लिए ऐक्सेस टोकन पाने के लिए, 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 का इस्तेमाल करें.

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