กิจกรรม

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

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

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

Google Cloud Pub/Sub

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

• ดูข้อมูลเบื้องต้นเกี่ยวกับ Pub/Sub ได้จาก คำแนะนำวิธีใช้
• ทำความเข้าใจวิธีการทำงานของการตรวจสอบสิทธิ์
• เลือกไลบรารีของไคลเอ็นต์ที่ระบุ หรือเขียนไลบรารีของคุณเองและใช้ REST/HTTP หรือ gRPC API Surfaces

การสมัครใช้บริการกิจกรรม

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

projects/gcp-project-name/subscriptions/topic-id

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

เริ่มเหตุการณ์

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

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

ลำดับเหตุการณ์

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

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

รหัสผู้ใช้

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

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

เหตุการณ์ความสัมพันธ์

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

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

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

เพย์โหลดสําหรับเหตุการณ์ความสัมพันธ์มีดังนี้

{
  "eventId" : "7272c69e-a61a-42b4-b4ad-f92eeeedf64d",
  "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เชื่อมโยงกับโครงสร้างที่ได้รับอนุญาตของ userซึ่งทริกเกอร์เหตุการณ์

subject จะเป็นได้เพียงห้องหรือโครงสร้าง หาก a developer ไม่มี สิทธิ์ดูโครงสร้างของ usersubject จะว่างเปล่าเสมอ

ช่อง

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

ตัวอย่าง

เพย์โหลดของเหตุการณ์จะแตกต่างกันไปตามเหตุการณ์ความสัมพันธ์แต่ละประเภท ดังนี้

"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" : "46aa261f-ffd3-4499-8f56-2b277ff6c5c2",
  "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"
  ]
}

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

เหตุการณ์ที่สร้างขึ้นเพื่อตอบสนองต่อการดำเนินการของอุปกรณ์ซึ่งไม่ได้เปลี่ยนฟิลด์ลักษณะจะมี เพย์โหลดที่มีออบเจ็กต์ resourceUpdate แต่มีออบเจ็กต์ events แทนออบเจ็กต์ traits

{
  "eventId" : "e4ebb38d-dd17-4c94-ba9d-ad491d60b1c4",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "00ZMrfd4kP1zafPtO2yUlXdwz-...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

ช่อง

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

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

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

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

ระบบจะจัดกลุ่มกิจกรรมประเภทต่างๆ ไว้ในเธรดที่แตกต่างกันเพื่อวัตถุประสงค์ในการแจ้งเตือน

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

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

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

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

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

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

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

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

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

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

บัญชีบริการ

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

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

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

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับ 2LO ของ Google และวิธีตั้งค่าได้ที่การใช้ 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 และเพิ่มตำแหน่งของ Go ลงใน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

ข้อผิดพลาด

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

ดูรายการรหัสข้อผิดพลาดของ API ทั้งหมดได้ที่เอกสารอ้างอิงรหัสข้อผิดพลาดของ API