เหตุการณ์ไม่พร้อมกันและจัดการโดย Google Cloud Pub/Sub ในหัวข้อเดียวต่อ Projectกิจกรรมจะช่วยให้มีการอัปเดตสำหรับอุปกรณ์และโครงสร้างทั้งหมด รวมถึงการรับเหตุการณ์ตราบใดที่ผู้ใช้ไม่เพิกถอนโทเค็นเพื่อการเข้าถึงและข้อความเหตุการณ์ยังไม่หมดอายุ
เปิดใช้กิจกรรม
เหตุการณ์คือฟีเจอร์เสริมของ SDM API โปรดดู เปิดใช้เหตุการณ์ เพื่อดูวิธีเปิดใช้เหตุการณ์สำหรับ Project
Pub/Sub ของ Google Cloud
ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีการทำงานของ Pub/Sub ได้ในเอกสารประกอบเกี่ยวกับ Google Cloud Pub/Sub โดยเฉพาะอย่างยิ่งฟีเจอร์ต่อไปนี้
- ดูข้อมูลเบื้องต้นเกี่ยวกับ Pub/Sub จากคำแนะนำวิธีใช้
- ทำความเข้าใจวิธีการทำงานของการตรวจสอบสิทธิ์
- เลือกไลบรารีของไคลเอ็นต์ที่มีให้หรือเขียนข้อมูลของคุณเองและใช้แพลตฟอร์ม REST/HTTP หรือ gRPC API
การสมัครรับข้อมูลกิจกรรม
เมื่อเปิดใช้เหตุการณ์สำหรับ 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 ดังนี้
- เปิดใช้ Cloud Pub/Sub API ใน Google Cloud
- สร้างบัญชีบริการและคีย์บัญชีบริการตามที่อธิบายไว้ในการสร้างบัญชีบริการ เราขอแนะนำให้มอบเฉพาะบทบาทผู้สมัครใช้บริการ Pub/Sub เท่านั้น อย่าลืมดาวน์โหลดคีย์บัญชีบริการไปยังเครื่องที่จะใช้ Pub/Sub API
- ระบุข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ (คีย์บัญชีบริการ) ลงในโค้ดแอปพลิเคชันโดยทำตามวิธีการในหน้านั้นในขั้นตอนก่อนหน้า หรือรับโทเค็นเพื่อการเข้าถึงด้วยตนเองโดยใช้
oauth2l
หากต้องการทดสอบการเข้าถึง API อย่างรวดเร็ว - ใช้ข้อมูลเข้าสู่ระบบของบัญชีบริการหรือโทเค็นเพื่อการเข้าถึงกับ Pub/Sub
project.subscriptions
API เพื่อดึงและรับทราบข้อความ
OAuth2L
Google oauth2l
เป็นเครื่องมือบรรทัดคำสั่งสำหรับ OAuth ที่เขียนใน Go ติดตั้งสำหรับ Mac หรือ Linux โดยใช้ Go
- หากยังไม่มี Go ในระบบ ให้ดาวน์โหลดและติดตั้งก่อน
- เมื่อติดตั้ง Go แล้ว ให้ติดตั้ง
oauth2l
และเพิ่มตำแหน่งลงในตัวแปรสภาพแวดล้อมPATH
ดังนี้go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
- ใช้
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