เหตุการณ์เป็นแบบไม่พร้อมกันและจัดการโดย 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 ในหัวข้อนั้น ทั้งนี้ขึ้นอยู่กับ Use Case ของคุณ รองรับการสมัครรับข้อมูลหัวข้อ SDM หลายรายการ ดูข้อมูลเพิ่มเติมได้ในการจัดการการสมัครใช้บริการ
เริ่มต้นเหตุการณ์
หากต้องการเริ่มเหตุการณ์เป็นครั้งแรกเมื่อสร้างการสมัครใช้บริการ Pub/Sub แล้ว ให้เรียก API
devices.list
เป็นทริกเกอร์แบบครั้งเดียว เหตุการณ์สำหรับโครงสร้างและอุปกรณ์ทั้งหมดจะเผยแพร่หลังการเรียกนี้
ตัวอย่างเช่น ดูหน้าการให้สิทธิ์ในคู่มือเริ่มใช้งานฉบับย่อ
ลำดับของกิจกรรม
Pub/Sub ไม่รับประกันว่าจะมีการส่งเหตุการณ์ตามลำดับ และลำดับการรับเหตุการณ์อาจไม่สอดคล้องกับลำดับเหตุการณ์ที่เกิดขึ้นจริง ใช้ช่อง timestamp
เพื่อช่วยในการปรับยอดลำดับเหตุการณ์ กิจกรรมอาจมาถึงทีละรายการหรือรวมกันเป็นข้อความเหตุการณ์เดียวก็ได้
ดูข้อมูลเพิ่มเติมได้ที่การเรียงลำดับข้อความ
รหัสผู้ใช้
หากการใช้งานอิงตามผู้ใช้ (ไม่ใช่ตามโครงสร้างหรืออุปกรณ์) ให้ใช้ช่อง userID
จากเพย์โหลดเหตุการณ์เพื่อเชื่อมโยงทรัพยากรและเหตุการณ์ ช่องนี้เป็นรหัสที่ปรับให้ยากต่อการอ่าน (Obfuscate) ซึ่งแสดงถึงผู้ใช้ที่เฉพาะเจาะจง
นอกจากนี้ userID
พร้อมใช้งานในส่วนหัวการตอบกลับ HTTP ของการเรียก API แต่ละรายการด้วย
กิจกรรมความสัมพันธ์
กิจกรรมความสัมพันธ์หมายถึงการอัปเดตเชิงสัมพันธ์สำหรับทรัพยากร เช่น เมื่อมีการเพิ่มอุปกรณ์ลงในโครงสร้างหรือเมื่อมีการลบอุปกรณ์ออกจากโครงสร้าง
เหตุการณ์ความสัมพันธ์มี 3 ประเภทดังนี้
- สร้างแล้ว
- ลบแล้ว
- อัปเดตแล้ว
เพย์โหลดของเหตุการณ์ที่เกี่ยวข้องมีดังนี้
เพย์โหลด
{ "eventId" : "eed9763a-8735-45d9-81d9-e0621c130eb1", "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 ตัวอย่างเช่น "1362476b-4ac4-4608-a8be-4c8cf4101426" |
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" }
ระบบจะไม่ส่งเหตุการณ์ความสัมพันธ์ในกรณีต่อไปนี้
- ลบห้องแล้ว
เหตุการณ์ของทรัพยากร
เหตุการณ์ทรัพยากรแสดงถึงการอัปเดตของทรัพยากรหนึ่งๆ โดยเฉพาะ สามารถตอบสนองต่อการเปลี่ยนแปลงค่าของช่องลักษณะได้ เช่น การเปลี่ยนโหมดของตัวควบคุมอุณหภูมิ นอกจากนี้ ยังอาจแสดงการทำงานของอุปกรณ์ที่ไม่เปลี่ยนแปลงช่องลักษณะ เช่น การกดปุ่มของอุปกรณ์
เหตุการณ์ที่สร้างขึ้นเพื่อตอบสนองต่อการเปลี่ยนแปลงค่าของช่องลักษณะมีออบเจ็กต์ traits
ซึ่งคล้ายกับการเรียก GET ของอุปกรณ์
เพย์โหลด
{
"eventId" : "5b98a768-6771-4d4d-836d-58cce3a62cca",
"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" : "3426d266-406b-48f3-9595-5192229a39a0",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion
" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "8XZ1cQ76Becovj551YfM9ZnuwB...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }
เหตุการณ์ทรัพยากรประเภทเหล่านี้จะได้รับการกําหนดลักษณะที่เฉพาะเจาะจง ตัวอย่างเช่น มีการกำหนดเหตุการณ์การเคลื่อนไหวไว้ในลักษณะ cameraMotion โปรดดูเอกสารของแต่ละลักษณะเพื่อทำความเข้าใจรูปแบบเพย์โหลดสำหรับเหตุการณ์ทรัพยากรประเภทเหล่านี้
ช่อง
ฟิลด์ | คำอธิบาย | ประเภทข้อมูล |
---|---|---|
eventId |
ตัวระบุที่ไม่ซ้ำกันสำหรับกิจกรรม | string ตัวอย่างเช่น "3426d266-406b-48f3-9595-5192229a39a0" |
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 จะจัดการการจัดกลุ่มชุดข้อความและตรรกะการจับเวลา และอาจมีการเปลี่ยนแปลงได้ทุกเมื่อ developer ควรอัปเดตการแจ้งเตือนตามเทรดเหตุการณ์และเซสชันที่ SDM API มีให้
สถานะชุดข้อความ
เหตุการณ์ที่รองรับการแจ้งเตือนที่อัปเดตได้จะมีช่อง eventThreadState
ที่ระบุสถานะของชุดข้อความเหตุการณ์ ณ เวลานั้นด้วย โดยช่องนี้มีค่าต่อไปนี้
- เริ่มแล้ว — เหตุการณ์แรกในชุดข้อความเหตุการณ์
- อัปเดตแล้ว — เหตุการณ์ในชุดข้อความเหตุการณ์ที่ดำเนินอยู่ ชุดข้อความเดียวอาจมีเหตุการณ์ที่มีสถานะนี้ไม่ได้อย่างน้อย 1 รายการ
- สิ้นสุดแล้ว — เหตุการณ์สุดท้ายในชุดข้อความเหตุการณ์ ซึ่งอาจซ้ำกับเหตุการณ์ที่อัปเดตล่าสุด โดยขึ้นอยู่กับประเภทของชุดข้อความ
ช่องนี้ใช้เพื่อติดตามความคืบหน้าของชุดข้อความเหตุการณ์และเมื่อชุดข้อความสิ้นสุดลงได้
การกรองเหตุการณ์
ในบางกรณี เหตุการณ์ที่อุปกรณ์ตรวจพบอาจถูกกรองออกจากการเผยแพร่ไปยังหัวข้อ SDM Pub/Sub ลักษณะการทำงานนี้เรียกว่าการกรองเหตุการณ์ วัตถุประสงค์ของการกรองเหตุการณ์คือหลีกเลี่ยงการเผยแพร่ข้อความเหตุการณ์ที่คล้ายกันมากเกินไปในระยะเวลาสั้นๆ
ตัวอย่างเช่น ข้อความอาจเผยแพร่ไปยังหัวข้อ SDM สำหรับเหตุการณ์การเคลื่อนไหวเริ่มต้น ข้อความอื่นๆ สำหรับภาพเคลื่อนไหวหลังจากนั้นจะถูกกรองออกจากการเผยแพร่จนกว่าจะผ่านระยะเวลาที่กำหนด เมื่อผ่านระยะเวลาดังกล่าวไปแล้ว ระบบอาจเผยแพร่ข้อความกิจกรรมสำหรับประเภทกิจกรรมนั้นอีกครั้ง
ในแอป Google Home (GHA) เหตุการณ์ที่กรองแล้วจะยังคงแสดงในประวัติกิจกรรมของ userแต่เหตุการณ์ดังกล่าวจะไม่สร้างการแจ้งเตือนแอป (แม้ว่าจะเปิดใช้การแจ้งเตือนประเภทนั้นก็ตาม)
เหตุการณ์แต่ละประเภทมีตรรกะการกรองเหตุการณ์ของตัวเอง ซึ่งกำหนดโดย Google และอาจมีการเปลี่ยนแปลงได้ทุกเมื่อ ตรรกะการกรองเหตุการณ์นี้ ไม่เกี่ยวข้องกับเทรดเหตุการณ์และตรรกะของเซสชัน
บัญชีบริการ
เราขอแนะนำให้ใช้บัญชีบริการเพื่อจัดการการสมัครใช้บริการ SDM API และข้อความเหตุการณ์ แอปพลิเคชันหรือเครื่องเสมือนใช้บัญชีบริการ ไม่ใช่บุคคล และมีคีย์บัญชีที่ไม่ซ้ำกันเป็นของตัวเอง
การให้สิทธิ์บัญชีบริการสำหรับ Pub/Sub API ใช้ OAuth แบบสองทาง (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