เหตุการณ์เป็นแบบไม่พร้อมกันและจัดการโดย Google Cloud Pub/Sub ในหัวข้อเดียวตาม Projectเหตุการณ์มีการอัปเดตสําหรับอุปกรณ์และโครงสร้างทั้งหมด และการได้รับเหตุการณ์คือ ตราบใดที่ผู้ใช้ไม่เพิกถอนโทเค็นเพื่อการเข้าถึง และข้อความเหตุการณ์ไม่ หมดอายุแล้ว
เปิดใช้กิจกรรม
เหตุการณ์คือฟีเจอร์เสริมของ SDM API โปรดดู เปิดใช้งานกิจกรรม เพื่อดูวิธีเปิดใช้การตั้งค่าดังกล่าวสำหรับ Project
Pub/Sub ของ Google Cloud
โปรดดูข้อมูลในเอกสารประกอบเกี่ยวกับ Google Cloud Pub/Sub ข้อมูลเพิ่มเติมเกี่ยวกับวิธีการทำงานของ Pub/Sub โดยเฉพาะอย่างยิ่งฟีเจอร์ต่อไปนี้
- เรียนรู้พื้นฐานของ Pub/Sub จาก คำแนะนำวิธีใช้
- ทำความเข้าใจวิธีการทำงานของการตรวจสอบสิทธิ์
- เลือกไลบรารีของไคลเอ็นต์ที่มีให้ หรือเขียนขึ้นเองและใช้ แพลตฟอร์ม REST/HTTP หรือ gRPC API
การสมัครรับข้อมูลกิจกรรม
เมื่อเปิดใช้เหตุการณ์สำหรับ Projectคุณจะได้รับหัวข้อเฉพาะ Project รหัสในรูปแบบดังนี้
projects/sdm-prod/topics/enterprise-project-id
หากต้องการรับเหตุการณ์ ให้สร้างพุลหรือ พุชการติดตามหัวข้อนั้น โดยขึ้นอยู่กับ Use Case ระบบรองรับการสมัครใช้บริการหัวข้อ SDM หลายรายการ โปรดดู การจัดการการสมัครใช้บริการสำหรับข้อมูลเพิ่มเติม
เริ่มกิจกรรม
หากต้องการเริ่มเหตุการณ์เป็นครั้งแรกเมื่อสร้างการสมัครใช้บริการ Pub/Sub แล้ว ให้สร้าง
devices.list
การเรียก API เป็นทริกเกอร์แบบครั้งเดียว ระบบจะเผยแพร่เหตุการณ์สำหรับโครงสร้างและอุปกรณ์ทั้งหมดหลังจากนี้
โทร
ตัวอย่างเช่น ดูที่ หน้าให้สิทธิ์ในการเริ่มต้นอย่างรวดเร็ว Guide
ลำดับของกิจกรรม
Pub/Sub ไม่ได้รับประกันการส่งมอบกิจกรรมตามลำดับ และลำดับการรับกิจกรรมอาจไม่แสดง
จะสอดคล้องกับลำดับเหตุการณ์ที่เกิดขึ้นจริง ใช้ timestamp
เพื่อช่วยปรับยอดลำดับเหตุการณ์ กิจกรรมอาจมาถึงทีละรายการหรือรวมกันด้วย
ไว้ในข้อความเหตุการณ์เดียว
สำหรับข้อมูลเพิ่มเติม โปรดดู การเรียงลำดับข้อความ
รหัสผู้ใช้
หากการติดตั้งใช้งานของคุณขึ้นอยู่กับผู้ใช้ (ไม่ใช่ตามโครงสร้างหรืออุปกรณ์) ให้ใช้
userID
จากเพย์โหลดของเหตุการณ์เพื่อเชื่อมโยงทรัพยากรและเหตุการณ์ ช่องนี้
รหัสที่ปรับให้ยากต่อการอ่าน (Obfuscate) สำหรับใช้แทนผู้ใช้ที่เฉพาะเจาะจง
userID
มีอยู่ในส่วนหัวการตอบกลับ HTTP ของการเรียก API แต่ละรายการด้วย
กิจกรรมความสัมพันธ์
เหตุการณ์ความสัมพันธ์จะแสดงการอัปเดตเชิงสัมพันธ์สำหรับทรัพยากร เช่น เมื่ออุปกรณ์กำลัง หรือเมื่ออุปกรณ์ถูกลบออกจากโครงสร้าง
เหตุการณ์ความสัมพันธ์มี 3 ประเภท ได้แก่
- สร้างเมื่อ
- ลบแล้ว
- อัปเดตแล้ว
เพย์โหลดสำหรับเหตุการณ์ที่เกี่ยวข้องมีดังนี้
เพย์โหลด
{ "eventId" : "096cde55-2e67-4708-8b0d-1ca0913b077d", "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 เช่น "94099140-e525-4e12-92b6-2226a521f6d5" |
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" : "64473d81-d201-4e29-8281-ac74ac22e24f",
"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" : "ad458fd9-a64a-45ed-a183-79f74538336b",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion
" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "TkahNphxcly8HACE4M5B9pHMoF...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }
เหตุการณ์ทรัพยากรประเภทเหล่านี้ได้รับการกำหนดตามลักษณะที่เฉพาะเจาะจง ตัวอย่างเช่น พารามิเตอร์ มีการระบุเหตุการณ์การเคลื่อนไหวใน CameraMotion trait. ดูเอกสารประกอบของลักษณะแต่ละอย่าง เพื่อทำความเข้าใจรูปแบบเพย์โหลดสำหรับเหตุการณ์ทรัพยากรประเภทเหล่านี้
ช่อง
ช่อง | คำอธิบาย | ประเภทข้อมูล |
---|---|---|
eventId |
ตัวระบุที่ไม่ซ้ำกันสำหรับกิจกรรม | string เช่น "ad458fd9-a64a-45ed-a183-79f74538336b" |
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 สำหรับเหตุการณ์การเคลื่อนไหวเริ่มต้น อื่นๆ ข้อความสำหรับ Motion หลังจากนั้นจะ ถูกกรองออกจากการเผยแพร่จนกว่าจะผ่านระยะเวลาที่กำหนดไว้ เมื่อช่วงเวลาดังกล่าว เมื่อเวลาผ่านไป ข้อความเหตุการณ์สำหรับประเภทเหตุการณ์นั้นอาจมีการเผยแพร่อีกครั้ง
ในแอป Google Home (GHA) เหตุการณ์ที่ ที่กรองแล้วจะยังคงแสดงในประวัติกิจกรรมของ userอย่างไรก็ตาม จะไม่สร้างการแจ้งเตือนของแอป (แม้ว่าประเภทการแจ้งเตือนนั้นจะเป็น เปิดอยู่)
เหตุการณ์แต่ละประเภทมีตรรกะการกรองเหตุการณ์ของตัวเอง ซึ่งกำหนดโดย Google และอาจมีการเปลี่ยนแปลงได้ตลอดเวลา ตรรกะการกรองเหตุการณ์นี้คือ โดยไม่ขึ้นอยู่กับเทรดเหตุการณ์และตรรกะเซสชัน
บัญชีบริการ
เราขอแนะนำให้ใช้บัญชีบริการสำหรับการจัดการ SDM API การสมัครรับข้อมูลและข้อความกิจกรรม แอปพลิเคชันใช้บัญชีบริการหรือ เครื่องเสมือน ไม่ใช่บุคคล และมีคีย์บัญชีที่ไม่ซ้ำกันเป็นของตัวเอง
การให้สิทธิ์บัญชีบริการสำหรับการใช้งาน Pub/Sub API OAuth แบบ 2 ทาง (2LO)
ในขั้นตอนการให้สิทธิ์ 2LO ให้ดำเนินการดังนี้
- developer ขอโทเค็นเพื่อการเข้าถึงโดยใช้คีย์บริการ
- developer ใช้โทเค็นเพื่อการเข้าถึงกับการเรียก API
หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับ Google 2LO และวิธีการตั้งค่า โปรดดู การใช้ OAuth 2.0 สำหรับเซิร์ฟเวอร์ต่อเซิร์ฟเวอร์ แอปพลิเคชัน
การให้สิทธิ์
บัญชีบริการควรได้รับอนุญาตให้ใช้กับ API Pub/Sub:
- เปิดใช้ Cloud Pub/Sub API ใน Google Cloud
- สร้างบัญชีบริการและคีย์บัญชีบริการตามที่อธิบายไว้ใน การสร้างบัญชีบริการ เราขอแนะนำให้มอบเฉพาะบทบาทผู้สมัครใช้บริการ Pub/Sub เท่านั้น อย่าลืม ดาวน์โหลดคีย์บัญชีบริการไปยังเครื่องที่จะใช้ API Pub/Sub
- ระบุข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ (คีย์บัญชีบริการ) ลงใน
โค้ดของแอปพลิเคชันโดยปฏิบัติตามคำแนะนำในหน้าใน
หรือได้รับโทเค็นเพื่อการเข้าถึงด้วยตนเองโดยใช้
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 ทั้งหมด