ইভেন্ট

ইভেন্টগুলি অ্যাসিঙ্ক্রোনাস এবং Google Cloud Pub/Sub দ্বারা পরিচালিত হয়, প্রতিটি Project-এর জন্য একটি একক বিষয়ে। ইভেন্ট সব ডিভাইস ও স্ট্রাকচারের জন্য আপডেট প্রদান করে এবং ইভেন্ট সংক্রান্ত মেসেজের মেয়াদ শেষ না হওয়া পর্যন্ত এবং ব্যবহারকারী অ্যাক্সেস টোকেন প্রত্যাহার না করা পর্যন্ত ইভেন্ট সংক্রান্ত মেসেজ পাওয়ার ব্যাপারে নিশ্চিত থাকা যায়।

ইভেন্টগুলি সক্ষম করুন

ইভেন্ট হল SDM API-এর একটি ঐচ্ছিক ফিচার। ইভেন্ট চালু করুন বিকল্পে ক্লিক করে আপনার Project-এর জন্য কীভাবে সেগুলি চালু করবেন তা জানুন।

Google Cloud Pub/Sub

Pub/Sub কীভাবে কাজ করে সেই সম্পর্কে আরও জানতে Google Cloud Pub/Sub ডকুমেন্টেশন দেখুন। বিশেষ করে এতে:

• Pub/Sub-এর প্রাথমিক বিষয়গুলি সম্পর্কে জানতে কীভাবে করবেন সংক্রান্ত নির্দেশিকা দেখুন।
• যাচাইকরণ কীভাবে কাজ করে তা বুঝুন।
• প্রদান করা ক্লায়েন্ট লাইব্রেরি বেছে নিন অথবা আপনার নিজেরটি লিখুন এবং REST/HTTP বা gRPC API সারফেস ব্যবহার করুন।

ইভেন্ট সাবস্ক্রিপশন

জানুয়ারি ২০২৫-এর আগে, আপনার Project-এর জন্য ইভেন্ট চালু করা থাকলে, আপনাকে সেই Project আইডি-র জন্য নির্দিষ্ট Google-হোস্ট করা বিষয় প্রদান করা হত, যা এই ফর্ম্যাটে থাকত:

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

সব প্রোজেক্টকে এখন তাদের নিজস্ব Google Cloud প্রোজেক্টে Pub/Sub টপিক সেল্ফ-হোস্ট করতে হবে (জানুয়ারি ২০২৫ থেকে নতুন প্রোজেক্টের জন্য বাধ্যতামূলক এবং ৩০ নভেম্বর, ২০২৬-এর মধ্যে সব বিদ্যমান প্রোজেক্টের জন্য প্রয়োজনীয়), এই ফর্ম্যাটে:

projects/gcp-project-name/subscriptions/topic-id

আপনার project যদি আগে থেকেই আপনার নিজের Google Cloud প্রোজেক্টে সেল্ফ-হোস্টেড টপিক ব্যবহার করে, তাহলে কোনও অ্যাকশন নিতে হবে না। আপনার Pub/Sub বিষয় কনফিগারেশন মাইগ্রেট করলে, আগে থেকে থাকা ব্যবহারকারীর অ্যাক্সেস টোকেন বা OAuth অনুমতি বাতিল হয়ে যায় না। সেল্ফ-হোস্টেড টপিক ও সাবস্ক্রিপশন স্ট্যান্ডার্ড Google Cloud Pub/Sub-এর দাম (যার মধ্যে প্রতি মাসে ১০ জিবি ফ্রি টিয়ার অন্তর্ভুক্ত) অনুযায়ী চার্জ করা হয়। আরও তথ্যের জন্য বিষয় তৈরি করুন দেখুন।

ইভেন্ট পেতে, আপনার ব্যবহারের ক্ষেত্রের উপর নির্ভর করে, সেই বিষয়ের জন্য একটি পুল বা পুশ সাবস্ক্রিপশন তৈরি করুন। SDM বিষয়ে একাধিক সাবস্ক্রিপশন কাজ করে। আরও তথ্যের জন্য সাবস্ক্রিপশন ম্যানেজ করা দেখুন।

ইভেন্ট শুরু করা

Pub/Sub সাবস্ক্রিপশন তৈরি হয়ে যাওয়ার পরে প্রথমবার ইভেন্ট শুরু করতে, ওয়ান-টাইম ট্রিগার হিসেবে devices.list API কল করুন। এই কলের পরে সব স্ট্রাকচার ও ডিভাইসের জন্য ইভেন্ট প্রকাশ করা হবে।

উদাহরণস্বরূপ, দ্রুত শুরুর নির্দেশিকায় অনুমোদন করুন পৃষ্ঠাটি দেখুন।

ইভেন্টের অর্ডার

Pub/Sub ইভেন্টের অর্ডার করা ডেলিভারির গ্যারেন্টি দেয় না এবং ইভেন্টের রসিদ অর্ডার ইভেন্টগুলি আসলে যে ক্রমে ঘটেছে তার সাথে নাও মিলতে পারে। ইভেন্ট অর্ডার রিকনসিলিয়েশনে সাহায্য করার জন্য timestamp ফিল্ড ব্যবহার করুন। এছাড়াও, ইভেন্ট আলাদাভাবে বা একটি ইভেন্ট মেসেজে একত্রিত হয়ে আসতে পারে।

আরও তথ্যের জন্য, মেসেজ সাজানো দেখুন।

ব্যবহারকারীর আইডি

আপনার ইমপ্লিমেন্টেশন যদি ব্যবহারকারীর উপর ভিত্তি করে হয় (স্ট্রাকচার বা ডিভাইসের পরিবর্তে), তাহলে রিসোর্স ও ইভেন্টের মধ্যে সম্পর্ক স্থাপন করতে ইভেন্ট পেলোড থেকে userID ফিল্ড ব্যবহার করুন। এই ফিল্ডটি হল একটি অস্পষ্ট আইডি যা নির্দিষ্ট ব্যবহারকারীকে দেখায়।

এছাড়াও, প্রতিটি API কলের HTTP রেসপন্স হেডারে userID উপলভ্য।

সম্পর্কিত ইভেন্ট

সম্পর্কিত ইভেন্ট কোনও রিসোর্সের জন্য সম্পর্কিত আপডেটকে দেখায়। যেমন, কোনও ডিভাইস স্ট্রাকচারে যোগ করা হলে বা স্ট্রাকচার থেকে কোনও ডিভাইস মুছে ফেলা হলে।

তিন ধরনের সম্পর্ক ইভেন্ট আছে:

• তৈরি করা হয়েছে
• মোছা হয়েছে
• আপডেট করা হয়েছে

সম্পর্ক ইভেন্টের পেলোড নিচে দেওয়া হল:

{
  "eventId" : "78b596bf-84ac-46ff-898e-608519a3cec2",
  "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" : "5f7b7bd4-c014-4303-9fdc-9f4a103f07fb",
  "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" : "36a8de1e-ee94-4eea-814b-464c98fe57c8",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "VhzVySCwWUvB-PIcOaBnub4xS1...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

এই ধরনের রিসোর্স ইভেন্ট নির্দিষ্ট বৈশিষ্ট্যে সংজ্ঞায়িত করা হয়। যেমন, মোশন ইভেন্ট CameraMotion ট্রেটে সংজ্ঞায়িত করা আছে। এই ধরনের রিসোর্স ইভেন্টের জন্য পেলোড ফর্ম্যাট বুঝতে প্রতিটি বৈশিষ্ট্যের ডকুমেন্টেশন দেখুন।

ফিল্ড

বিভিন্ন ধরনের ইভেন্ট এবং সেগুলি কীভাবে কাজ করে সেই সম্পর্কে আরও তথ্যের জন্য ইভেন্ট দেখুন।

আপডেট করা যায় এমন বিজ্ঞপ্তি

আপডেট করা যায় এমন বিজ্ঞপ্তির জন্য ইভেন্ট ফিচার সাপোর্ট বেছে নিন এবং ডকুমেন্টেশনে আপডেট করা যায়  হিসেবে ট্যাগ করা হয়। এইসব ইভেন্টের পেলোডে eventThreadId নামে একটি অতিরিক্ত ফিল্ড থাকে। ব্যবহারকারীকে দেখানো হয়েছে এমন আগে থেকে থাকা বিজ্ঞপ্তি আপডেট করার উদ্দেশ্যে, আলাদা আলাদা ইভেন্ট একসাথে লিঙ্ক করতে এই ফিল্ড ব্যবহার করুন।

ইভেন্ট থ্রেড ও ইভেন্ট সেশন এক জিনিস নয়। ইভেন্ট থ্রেড একই থ্রেডে আগের ইভেন্টের জন্য আপডেট করা স্ট্যাটাস শনাক্ত করে। ইভেন্ট সেশন একে অপরের সাথে সম্পর্কিত আলাদা আলাদা ইভেন্ট শনাক্ত করে এবং কোনও নির্দিষ্ট ইভেন্ট সেশনের জন্য একাধিক ইভেন্ট থ্রেড থাকতে পারে।

বিজ্ঞপ্তি পাঠানোর উদ্দেশ্যে, বিভিন্ন ধরনের ইভেন্টকে বিভিন্ন থ্রেডে গ্রুপ করা হয়।

এই থ্রেড গ্রুপিং এবং টাইমিং লজিক Google দ্বারা পরিচালিত হয় এবং যেকোনও সময় পরিবর্তন হতে পারে। SDM API-এর মাধ্যমে প্রদান করা ইভেন্ট থ্রেড ও সেশনের উপর ভিত্তি করে A developer -এর বিজ্ঞপ্তি আপডেট করা উচিত।

থ্রেডের স্ট্যাটাস

আপডেট করা যায় এমন বিজ্ঞপ্তি যেসব ইভেন্টে কাজ করে, সেগুলিতে একটি eventThreadState ফিল্ডও থাকে যা সেই সময়ে ইভেন্ট থ্রেডের স্ট্যাটাস দেখায়। এই ফিল্ডে নিম্নলিখিত ভ্যালু আছে:

• শুরু হয়েছে — ইভেন্ট থ্রেডের প্রথম ইভেন্ট।
• আপডেট করা হয়েছে — চলমান ইভেন্ট থ্রেডের একটি ইভেন্ট। একটি থ্রেডে এই স্ট্যাটাস সহ শূন্য বা তার বেশি ইভেন্ট থাকতে পারে।
• ENDED — ইভেন্ট থ্রেডের শেষ ইভেন্ট, যা থ্রেডের ধরনের উপর নির্ভর করে শেষ UPDATED ইভেন্টের ডুপ্লিকেট হতে পারে।

কোনও ইভেন্ট থ্রেডের অগ্রগতি এবং এটি কখন শেষ হয়েছে তা ট্র্যাক করতে এই ফিল্ড ব্যবহার করা যেতে পারে।

ইভেন্ট ফিল্টার করা

কিছু ক্ষেত্রে, কোনও ডিভাইসের মাধ্যমে শনাক্ত করা ইভেন্ট SDM Pub/Sub বিষয়ে প্রকাশ করা থেকে ফিল্টার করে বাদ দেওয়া হতে পারে। এই আচরণকে ইভেন্ট ফিল্টারিং বলা হয়। ইভেন্ট ফিল্টার করার উদ্দেশ্য হল অল্প সময়ের মধ্যে অনেকগুলি একই ধরনের ইভেন্ট মেসেজ প্রকাশ করা এড়ানো।

যেমন, প্রাথমিক মোশন ইভেন্টের জন্য SDM টপিকে মেসেজ প্রকাশ করা হতে পারে। তারপরে, একটি নির্দিষ্ট সময়সীমা পার না হওয়া পর্যন্ত Motion-এর জন্য অন্যান্য মেসেজ প্রকাশ করা থেকে ফিল্টার করা হবে। সেই সময়সীমা পেরিয়ে গেলে, সেই ধরনের ইভেন্টের জন্য আবার ইভেন্ট মেসেজ প্রকাশ করা হতে পারে।

Google Home অ্যাপে (GHA), ফিল্টার করা ইভেন্টগুলি এখনও user-এর ইভেন্ট ইতিহাসে দেখাবে। তবে, এই ধরনের ইভেন্ট অ্যাপ বিজ্ঞপ্তি জেনারেট করে না (এমনকি সেই বিজ্ঞপ্তির ধরন চালু থাকলেও)।

প্রতিটি ধরনের ইভেন্টের নিজস্ব ইভেন্ট ফিল্টারিং লজিক আছে, যা Google দ্বারা সংজ্ঞায়িত এবং যেকোনও সময় পরিবর্তন সাপেক্ষ। এই ইভেন্ট ফিল্টারিং লজিক ইভেন্ট থ্রেড ও সেশন লজিক থেকে স্বতন্ত্র।

পরিষেবা অ্যাকাউন্ট

SDM API সাবস্ক্রিপশন ও ইভেন্ট মেসেজ ম্যানেজ করার জন্য পরিষেবা অ্যাকাউন্ট ব্যবহার করার সাজেশন দেওয়া হয়। কোনও অ্যাপ্লিকেশন বা ভার্চুয়াল মেশিন, কোনও ব্যক্তি নয়, পরিষেবা অ্যাকাউন্ট ব্যবহার করে এবং এর নিজস্ব অনন্য অ্যাকাউন্ট কী থাকে।

Pub/Sub API-এর জন্য পরিষেবা অ্যাকাউন্ট অথরাইজেশন টু-লেগড OAuth (2LO) ব্যবহার করে।

2LO অথরাইজেশন ফ্লোতে:

• developer সার্ভিস কী ব্যবহার করে অ্যাক্সেস টোকেনের অনুরোধ করে।
• developer API-তে কল করার জন্য অ্যাক্সেস টোকেন ব্যবহার করে।

Google 2LO এবং কীভাবে সেট-আপ করতে হয় সেই সম্পর্কে আরও জানতে, সার্ভার থেকে সার্ভার অ্যাপ্লিকেশনের জন্য OAuth 2.0 ব্যবহার করা দেখুন।

অনুমোদন

Pub/Sub API-এর সাথে ব্যবহার করার জন্য পরিষেবা অ্যাকাউন্ট অনুমোদিত হতে হবে:

1. Google Cloud-এ Cloud Pub/Sub API চালু করুন।
2. পরিষেবা অ্যাকাউন্ট তৈরি করা-তে যেভাবে বর্ণনা করা হয়েছে সেইভাবে পরিষেবা অ্যাকাউন্ট ও পরিষেবা অ্যাকাউন্ট কী তৈরি করুন। আমরা সাজেস্ট করি যে আপনি এটিকে শুধুমাত্র Pub/Sub সাবস্ক্রাইবার ভূমিকা দিন। Pub/Sub API ব্যবহার করবে এমন মেশিনে পরিষেবা অ্যাকাউন্টের কী ডাউনলোড করতে ভুলবেন না।
3. আগের ধাপে উল্লেখ করা পৃষ্ঠার নির্দেশাবলী অনুসরণ করে আপনার অ্যাপ্লিকেশন কোডে যাচাইকরণ সংক্রান্ত ক্রেডেনশিয়াল (পরিষেবা অ্যাকাউন্ট কী) প্রদান করুন অথবা আপনি যদি API অ্যাক্সেস দ্রুত পরীক্ষা করতে চান, তাহলে oauth2l ব্যবহার করে ম্যানুয়ালি অ্যাক্সেস টোকেন পান।
4. মেসেজ পুল ও অ্যাকনলেজ করতে Pub/Sub project.subscriptions API-এর সাথে পরিষেবা অ্যাকাউন্টের ক্রেডেনশিয়াল বা অ্যাক্সেস টোকেন ব্যবহার করুন।

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. API-এর জন্য অ্যাক্সেস টোকেন পেতে 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

সমস্যা

এই নির্দেশিকার সাথে সম্পর্কিত নিম্নলিখিত ত্রুটি কোড দেখানো হতে পারে:

API-তে হওয়া সমস্যার কোডের সম্পূর্ণ তালিকা দেখতে, API-তে হওয়া সমস্যার কোডের রেফারেন্স দেখুন।