กิจกรรม

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

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

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

Pub/Sub ของ Google Cloud

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

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

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

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

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

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

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

ตัวอย่างเช่น ดูที่ หน้าให้สิทธิ์ในการเริ่มต้นอย่างรวดเร็ว Guide

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

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

สำหรับข้อมูลเพิ่มเติม โปรดดู การเรียงลำดับข้อความ

รหัสผู้ใช้

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

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

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

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

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

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

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

เพย์โหลด

{
  "eventId" : "2e2d8266-270c-4ec5-8c45-7cb61e7c72f3",
  "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
เช่น "9a814c1f-d963-4d2f-8dea-e8b4eb8b4260"
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" : "5b700d2c-6c5f-4aac-8e47-a4016fb41217",
  "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" : "f550806b-5602-4fb2-a509-b440546390b7",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "bSyBw_twQcTZxfK76EMk4uQZyh...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }

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

ช่อง

ช่อง คำอธิบาย ประเภทข้อมูล
eventId ตัวระบุที่ไม่ซ้ำกันสำหรับกิจกรรม string
ตัวอย่าง: "f550806b-5602-4fb2-a509-b440546390b7"
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:

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