इवेंट

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

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

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

Google Cloud Pub/Sub

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

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

जब आपके Projectके लिए इवेंट चालू किए जाते हैं, तो आपको उस Project आईडी के हिसाब से एक विषय मिलेगा. यह विषय इस तरह दिखेगा:

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

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

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

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

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

इवेंट का क्रम

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

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

यूज़र आईडी

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

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

रिलेशन इवेंट

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

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

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

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

पेलोड

{
  "eventId" : "d5c0f0bd-de65-44fd-ac60-686c302e56eb",
  "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
उदाहरण: "64b87b46-1aec-42a4-8c01-997a407814df"
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"
}

रिलेशन इवेंट तब नहीं भेजे जाते, जब:

  • कोई रूम मिटाया जाता है

संसाधन इवेंट

रिसॉर्स इवेंट, किसी रिसॉर्स से जुड़े अपडेट को दिखाता है. यह किसी ट्रीट फ़ील्ड की वैल्यू में हुए बदलाव के जवाब में हो सकता है. जैसे, थर्मोस्टैट का मोड बदलना. यह किसी ऐसी डिवाइस कार्रवाई को भी दिखा सकता है जो किसी ट्रीट फ़ील्ड को बदलती नहीं है. जैसे, डिवाइस के बटन को दबाना.

ट्रेट फ़ील्ड की वैल्यू में हुए बदलाव के जवाब में जनरेट किए गए इवेंट में, डिवाइस के GET कॉल की तरह ही एक traits ऑब्जेक्ट होता है:

पेलोड

{
  "eventId" : "a88bc884-d2b8-42d6-adba-b7be92c232a3",
  "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" : "4f80de08-1b77-42a4-b33e-40876a2a1865",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "MWJ253hZMPAsJZJWbrGM4ThsKM...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }

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

फ़ील्ड

फ़ील्ड ब्यौरा डेटा टाइप
eventId इवेंट के लिए यूनीक आइडेंटिफ़ायर. string
उदाहरण: "4f80de08-1b77-42a4-b33e-40876a2a1865"
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 मैनेज करता है. इसे किसी भी समय बदला जा सकता है. SDM API से मिलने वाली इवेंट थ्रेड और सेशन के आधार पर, developer को सूचनाएं अपडेट करनी चाहिए.

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

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

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

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

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

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

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

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

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

सेवा खाते

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

Pub/Sub API के लिए सेवा खाते की अनुमति देने के लिए, दो लेग वाले OAuth (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 एपीआई के साथ सेवा खाते के क्रेडेंशियल या ऐक्सेस टोकन का इस्तेमाल करें.

oauth2l

Google oauth2l, Go में लिखा गया OAuth के लिए कमांड-लाइन टूल है. इसे 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 का इस्तेमाल करें.

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