กิจกรรม

เหตุการณ์เป็นแบบอะซิงโครนัสและจัดการโดย 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 ในรูปแบบต่อไปนี้

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

หากต้องการรับเหตุการณ์ ให้สร้างการสมัครใช้บริการแบบดึงหรือ พุชสำหรับหัวข้อนั้น ทั้งนี้ขึ้นอยู่กับ กรณีการใช้งาน ระบบรองรับการสมัครใช้บริการหัวข้อ SDM หลายรายการ ดูข้อมูลเพิ่มเติมได้ที่ การจัดการการสมัครใช้บริการ

เริ่มเหตุการณ์

หากต้องการเริ่มเหตุการณ์เป็นครั้งแรกเมื่อสร้างการสมัครใช้บริการ Pub/Sub แล้ว ให้เรียก API devices.list เป็นทริกเกอร์แบบครั้งเดียว ระบบจะเผยแพร่เหตุการณ์สำหรับโครงสร้างและอุปกรณ์ทั้งหมดหลังจากการเรียกนี้

ดูตัวอย่างได้ที่หน้า ให้สิทธิ์ในคู่มือเริ่มใช้งานฉบับย่อ

ลำดับเหตุการณ์

Pub/Sub ไม่รับประกันการส่งเหตุการณ์ตามลำดับ และลำดับการรับเหตุการณ์อาจไม่ ตรงกับลำดับที่เหตุการณ์เกิดขึ้นจริง ใช้ช่อง timestamp เพื่อช่วยในการกระทบยอดลำดับเหตุการณ์ นอกจากนี้ เหตุการณ์อาจมาถึงทีละรายการหรือรวมกัน เป็นข้อความเหตุการณ์เดียว

ดูข้อมูลเพิ่มเติมได้ที่ การจัดลำดับข้อความ

รหัสผู้ใช้

หากการติดตั้งใช้งานของคุณอิงตามผู้ใช้ (แทนที่จะเป็นโครงสร้างหรืออุปกรณ์) ให้ใช้ช่อง userID จากเพย์โหลดของเหตุการณ์เพื่อเชื่อมโยงทรัพยากรและเหตุการณ์ ช่องนี้คือ รหัสซับซ้อนที่แสดงถึงผู้ใช้ที่เฉพาะเจาะจง

นอกจากนี้ userID ยังมีอยู่ในส่วนหัวการตอบกลับ HTTP ของการเรียก API แต่ละครั้งด้วย

เหตุการณ์ความสัมพันธ์

เหตุการณ์ความสัมพันธ์แสดงถึงการอัปเดตความสัมพันธ์ของทรัพยากร เช่น เมื่อเพิ่มอุปกรณ์ลงในโครงสร้าง หรือเมื่อลบอุปกรณ์ออกจากโครงสร้าง

เหตุการณ์ความสัมพันธ์มี 3 ประเภท ได้แก่

• CREATED
• ลบแล้ว
• อัปเดตแล้ว

เพย์โหลดสำหรับเหตุการณ์ความสัมพันธ์มีลักษณะดังนี้

{
  "eventId" : "989d20a7-b812-4114-adca-5b5182595f66",
  "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's 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" : "d7c263f3-e545-44fa-a036-a7d286baf6ff",
  "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" : "8caf8edb-38b7-4d3e-9cd6-94cf01fc53c8",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "RUcV2bOLw1fL36jRbPDwXsBxLs...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

เหตุการณ์ของทรัพยากรประเภทเหล่านี้กำหนดไว้ในลักษณะที่เฉพาะเจาะจง เช่น เหตุการณ์การเคลื่อนไหว กำหนดไว้ในลักษณะ CameraMotion ดูเอกสารประกอบของแต่ละลักษณะ เพื่อทำความเข้าใจรูปแบบเพย์โหลดสำหรับเหตุการณ์ของทรัพยากรประเภทเหล่านี้

ช่อง

ดูข้อมูลเพิ่มเติมเกี่ยวกับเหตุการณ์ประเภทต่างๆ และวิธีการทำงานได้ที่เหตุการณ์

การแจ้งเตือนที่อัปเดตได้

เลือกเหตุการณ์ที่รองรับฟีเจอร์การแจ้งเตือนที่อัปเดตได้และติดแท็กเป็น อัปเดตได้  ในเอกสารประกอบ เหตุการณ์เหล่านี้มีช่องเพิ่มเติมที่เรียกว่า eventThreadId ในเพย์โหลด ใช้ช่องนี้เพื่อลิงก์เหตุการณ์แต่ละรายการเข้าด้วยกันเพื่อวัตถุประสงค์ในการอัปเดตการแจ้งเตือนที่มีอยู่ซึ่งแสดงต่อผู้ใช้

เธรดเหตุการณ์ไม่เหมือนกับเซสชันเหตุการณ์ เธรดเหตุการณ์ จะระบุสถานะที่อัปเดตแล้วสำหรับเหตุการณ์ก่อนหน้าในเธรดเดียวกัน เซสชันเหตุการณ์ จะระบุเหตุการณ์แยกกันที่เกี่ยวข้องกับเหตุการณ์อื่นๆ และอาจมีเธรดเหตุการณ์หลายรายการสำหรับเซสชันเหตุการณ์หนึ่งๆ

ระบบจะจัดกลุ่มเหตุการณ์ประเภทต่างๆ ไว้ในเธรดต่างๆ เพื่อวัตถุประสงค์ในการแจ้งเตือน

Google เป็นผู้จัดการตรรกะการจัดกลุ่มและการกำหนดเวลาของเธรดนี้ และอาจเปลี่ยนแปลงได้ทุกเมื่อ A developer ควรจะอัปเดตการแจ้งเตือนตาม เธรดและเซสชันเหตุการณ์ที่ SDM API ให้ไว้

สถานะเธรด

เหตุการณ์ที่รองรับการแจ้งเตือนที่อัปเดตได้จะมีช่อง eventThreadState ซึ่งระบุสถานะของเธรดเหตุการณ์ ณ จุดนั้นๆ ด้วย ช่องนี้มีค่าต่อไปนี้

• STARTED — เหตุการณ์แรกในเธรดเหตุการณ์
• UPDATED — เหตุการณ์ในเธรดเหตุการณ์ที่กำลังดำเนินอยู่ อาจมีเหตุการณ์ที่มีสถานะนี้ตั้งแต่ 0 รายการขึ้นไปในเธรดเดียว
• ENDED — เหตุการณ์สุดท้ายในเธรดเหตุการณ์ ซึ่งอาจเป็นเหตุการณ์ UPDATED รายการสุดท้ายที่ซ้ำกัน ทั้งนี้ขึ้นอยู่กับประเภทเธรด

คุณสามารถใช้ช่องนี้เพื่อติดตามความคืบหน้าของเธรดเหตุการณ์และเวลาที่เธรดสิ้นสุด

การกรองเหตุการณ์

ในบางกรณี ระบบอาจกรองเหตุการณ์ที่อุปกรณ์ตรวจพบออกจากการเผยแพร่ไปยังหัวข้อ SDM Pub/Sub ลักษณะการทำงานนี้เรียกว่าการกรองเหตุการณ์ วัตถุประสงค์ของการกรองเหตุการณ์คือเพื่อหลีกเลี่ยงการเผยแพร่ข้อความเหตุการณ์ที่คล้ายกันมากเกินไปในระยะเวลาอันสั้น

เช่น ระบบอาจเผยแพร่ข้อความไปยังหัวข้อ SDM สำหรับเหตุการณ์การเคลื่อนไหวเริ่มต้น ข้อความอื่นๆ สำหรับการเคลื่อนไหวหลังจากนั้นจะถูกกรองออกจากการเผยแพร่จนกว่าจะผ่านระยะเวลาที่กำหนด เมื่อผ่านระยะเวลาดังกล่าวแล้ว ระบบอาจเผยแพร่ข้อความเหตุการณ์สำหรับเหตุการณ์ประเภทนั้นอีกครั้ง

ในแอป Google Home (GHA) เหตุการณ์ที่ กรองแล้วจะยังคงแสดงใน user's ประวัติเหตุการณ์ อย่างไรก็ตาม เหตุการณ์ดังกล่าวจะไม่สร้างการแจ้งเตือนของแอป (แม้ว่าจะเปิดใช้การแจ้งเตือนประเภทนั้นอยู่)

เหตุการณ์แต่ละประเภทมีตรรกะการกรองเหตุการณ์ของตัวเอง ซึ่งกำหนดโดย Google และอาจเปลี่ยนแปลงได้ทุกเมื่อ ตรรกะการกรองเหตุการณ์นี้ไม่ขึ้นอยู่กับตรรกะเธรดและเซสชันเหตุการณ์

บัญชีบริการ

เราขอแนะนำให้ใช้บัญชีบริการเพื่อจัดการการสมัครใช้บริการ SDM API และข้อความเหตุการณ์ บัญชีบริการใช้โดยแอปพลิเคชันหรือเครื่องเสมือน ไม่ใช่บุคคล และมีคีย์บัญชีที่ไม่ซ้ำกันของตัวเอง

การให้สิทธิ์บัญชีบริการสำหรับ Pub/Sub API ใช้ OAuth แบบ 2 ทาง (2LO)

ในขั้นตอนการให้สิทธิ์ 2LO

• จะขอโทเค็นเพื่อการเข้าถึงโดยใช้คีย์บริการ developer
• จะใช้โทเค็นเพื่อการเข้าถึงกับการเรียก API developer

ดูข้อมูลเพิ่มเติมเกี่ยวกับ Google 2LO และวิธีตั้งค่าได้ที่ การใช้ OAuth 2.0 สำหรับแอปพลิเคชันที่มีการโต้ตอบระหว่างเซิร์ฟเวอร์กับเซิร์ฟเวอร์

การให้สิทธิ์

ควรให้สิทธิ์บัญชีบริการเพื่อใช้กับ Pub/Sub API โดยทำดังนี้

1. เปิดใช้ Cloud Pub/Sub API ใน Google Cloud
2. สร้างบัญชีบริการและคีย์บัญชีบริการตามที่อธิบายไว้ใน การสร้างบัญชีบริการ เราขอแนะนำให้กำหนดบทบาทผู้สมัครใช้บริการ Pub/Sub ให้เท่านั้น อย่าลืมดาวน์โหลดคีย์บัญชีบริการลงในเครื่องที่จะใช้ Pub/Sub API
3. ระบุข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ (คีย์บัญชีบริการ) ให้กับโค้ดของแอปพลิเคชันโดยทำตามวิธีการในหน้าของขั้นตอนก่อนหน้า หรือรับโทเค็นเพื่อการเข้าถึงด้วยตนเองโดยใช้ oauth2l หากต้องการทดสอบการเข้าถึง API อย่างรวดเร็ว
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 เพื่อรับโทเค็นเพื่อการเข้าถึงสำหรับ API โดยใช้ขอบเขต 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 สำหรับ