กิจกรรม

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

เปิดใช้กิจกรรม

เหตุการณ์คือฟีเจอร์เสริมของ SDM API โปรดดู เปิดใช้เหตุการณ์ เพื่อดูวิธีเปิดใช้เหตุการณ์สำหรับ Project

Pub/Sub ของ Google Cloud

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีการทำงานของ Pub/Sub ได้ในเอกสารประกอบเกี่ยวกับ Google Cloud Pub/Sub โดยเฉพาะอย่างยิ่งฟีเจอร์ต่อไปนี้

การสมัครรับข้อมูลกิจกรรม

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

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

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

เริ่มกิจกรรม

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

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

ลำดับของกิจกรรม

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

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

รหัสผู้ใช้

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

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

กิจกรรมความสัมพันธ์

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

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

  • สร้างแล้ว
  • ลบแล้ว
  • อัปเดตแล้ว

เพย์โหลดสำหรับเหตุการณ์ที่เกี่ยวข้องมีดังนี้

เพย์โหลด

{
  "eventId" : "167a296a-d339-4626-a360-7a43475625e9",
  "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 ไม่มีสิทธิ์ดูโครงสร้างของ usersubject จะว่างเปล่าเสมอ

ช่อง

ฟิลด์ คำอธิบาย ประเภทข้อมูล
eventId ตัวระบุที่ไม่ซ้ำกันสำหรับกิจกรรม string
ตัวอย่างเช่น "effe1a42-5d9a-4b5b-a424-cc6bd145a977"
timestamp เวลาที่เกิดเหตุการณ์ string
เช่น "2019-01-01T00:00:01Z"
relationUpdate ออบเจ็กต์ที่ระบุรายละเอียดข้อมูลเกี่ยวกับการอัปเดตความสัมพันธ์ object
userId ตัวระบุที่ปรับให้ยากต่อการอ่าน (Obfuscate) ที่ไม่ซ้ำกันซึ่งแสดงถึงผู้ใช้ 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" : "b3f6755c-17e1-4b33-b5cc-32251142e7d6",
  "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" : "f67af755-e432-4b9a-9045-69e986896b3f",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "UNRMB1-mV7fXP4ncSo9E4B5Pbd...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }

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

ช่อง

ฟิลด์ คำอธิบาย ประเภทข้อมูล
eventId ตัวระบุที่ไม่ซ้ำกันสำหรับกิจกรรม string
ตัวอย่างเช่น "f67af755-e432-4b9a-9045-69e986896b3f"
timestamp เวลาที่เกิดเหตุการณ์ string
เช่น "2019-01-01T00:00:01Z"
resourceUpdate ออบเจ็กต์ที่ระบุรายละเอียดข้อมูลเกี่ยวกับการอัปเดตทรัพยากร object
userId ตัวระบุที่ปรับให้ยากต่อการอ่าน (Obfuscate) ที่ไม่ซ้ำกันซึ่งแสดงถึงผู้ใช้ string
เช่น "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
eventThreadId ตัวระบุที่ไม่ซ้ำกันสําหรับชุดข้อความเหตุการณ์ string
เช่น "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
eventThreadState สถานะของชุดข้อความเหตุการณ์ string
ค่า: "STARTED", "UPDATED", "ENDED"
resourceGroup ออบเจ็กต์ที่ระบุทรัพยากรที่อาจมีการอัปเดตที่คล้ายกันกับเหตุการณ์นี้ ทรัพยากรของเหตุการณ์ (จากออบเจ็กต์ resourceUpdate) จะแสดงอยู่ในออบเจ็กต์นี้เสมอ object

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

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

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

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

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

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

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

สถานะชุดข้อความ

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

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

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

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

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

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

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

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

บัญชีบริการ

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

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

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

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับ 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

ข้อผิดพลาด

ระบบอาจแสดงรหัสข้อผิดพลาดต่อไปนี้ซึ่งเกี่ยวข้องกับคู่มือนี้

ข้อความแสดงข้อผิดพลาด RPC การแก้ปัญหา
รูปภาพจากกล้องไม่พร้อมให้ดาวน์โหลดแล้ว DEADLINE_EXCEEDED รูปภาพกิจกรรมจะหมดอายุใน 30 วินาทีหลังจากเผยแพร่ โปรดดาวน์โหลดรูปภาพก่อนหมดอายุ
รหัสเหตุการณ์ไม่ได้อยู่ในกล้อง FAILED_PRECONDITION ใช้ eventID ที่ถูกต้องซึ่งแสดงผลจากเหตุการณ์จากกล้อง

ดูข้อมูลอ้างอิงรหัสข้อผิดพลาดของ API สำหรับรายการรหัสข้อผิดพลาดทั้งหมดของ API