กิจกรรม

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

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

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

Google Cloud Pub/Sub

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

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

การสมัครรับข้อมูลเหตุการณ์

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

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

ตอนนี้ทุกโปรเจ็กต์ต้องโฮสต์หัวข้อ Pub/Sub ด้วยตนเองในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของตนเอง (ต้องดำเนินการสำหรับโปรเจ็กต์ใหม่ตั้งแต่เดือนมกราคม 2025 และต้องดำเนินการสำหรับโปรเจ็กต์ที่มีอยู่ทั้งหมดภายในวันที่ 30 พฤศจิกายน 2026) ในรูปแบบต่อไปนี้

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

หาก project ใช้หัวข้อที่โฮสต์ด้วยตนเองในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ Google ของคุณอยู่แล้ว ก็ไม่จำเป็นต้องดำเนินการใดๆ การย้ายข้อมูลการกำหนดค่าหัวข้อ Pub/Sub จะไม่ทำให้โทเค็นเพื่อการเข้าถึงของผู้ใช้หรือสิทธิ์ OAuth ที่มีอยู่ใช้งานไม่ได้ หัวข้อและการสมัครใช้บริการที่โฮสต์ด้วยตนเองอยู่ภายใต้ราคา Google Cloud Pub/Sub มาตรฐาน (ซึ่งรวมถึงรุ่นฟรี 10 GB ต่อเดือน) ดูข้อมูลเพิ่มเติมได้ที่ สร้างหัวข้อ

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

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

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

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

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

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

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

รหัสผู้ใช้

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

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

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

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

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

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

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

{
  "eventId" : "c873a147-2a89-40ed-8ccb-68e8475430e1",
  "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 จะว่างเปล่าเสมอ

ช่อง

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

ตัวอย่าง

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

"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" : "16e90a37-d13b-4057-857b-127273cf9447",
  "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" : "f23283c6-968a-48c0-a92e-415577715b0e",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "V1y7sbSe1Bc_1aaJPwuk_qqpzU...",
      }
    }
  }
  "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 ซึ่งระบุสถานะของชุดข้อความของเหตุการณ์ ณ จุดเวลานั้นด้วย ฟิลด์นี้มีค่าดังนี้

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

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

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

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

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

ในแอป 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 ดังนี้

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 และเพิ่มตำแหน่งลงในตัวแปรสภาพแวดล้อม 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 APIs มีไลบรารีของไคลเอ็นต์หลายรายการที่ใช้ OAuth 2.0 ดูข้อมูลเพิ่มเติมเกี่ยวกับภาษาที่คุณเลือกได้ที่ไลบรารีของไคลเอ็นต์ Google API

เมื่อใช้ไลบรารีเหล่านี้กับ Pub/Sub APIให้ใช้สตริงขอบเขตต่อไปนี้

https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

ข้อผิดพลาด

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

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