Report State เป็นฟีเจอร์สำคัญที่ช่วยให้Google Home Action รายงานสถานะล่าสุดของอุปกรณ์ของผู้ใช้กลับไปยัง Google Home Graph ได้อย่างรวดเร็วแทนที่จะรอให้มีเจตนา QUERY
Report State รายงานสถานะของอุปกรณ์ของผู้ใช้ไปยัง Google
พร้อมagentUserId
ที่ระบุซึ่งเชื่อมโยงกับอุปกรณ์เหล่านั้น (ส่งในคำขอSYNC
เดิม) เมื่อ Google Assistant ต้องการดำเนินการ
ที่ต้องทำความเข้าใจสถานะปัจจุบันของอุปกรณ์ ก็เพียงแค่ค้นหา
ข้อมูลสถานะใน Home Graph แทน
การออกอินเทนต์ QUERY
ไปยังระบบคลาวด์ของบุคคลที่สามต่างๆ ก่อนที่จะออกอินเทนต์
EXECUTE
หากไม่มี Report State เมื่อมีหลอดไฟจากผู้ให้บริการหลายรายในห้องนั่งเล่น คำสั่ง Ok Google เพิ่มความสว่างในห้องนั่งเล่นหน่อย จะต้องQUERY
แก้ไขความตั้งใจหลายอย่างที่ส่งไปยังระบบคลาวด์หลายระบบ ซึ่งต่างจากQUERY
การค้นหาค่าความสว่างปัจจุบันตามค่าที่รายงานไว้ก่อนหน้านี้ เพื่อให้ผู้ใช้ได้รับประสบการณ์การใช้งานที่ดีที่สุด
Assistant ต้องมีสถานะปัจจุบันของอุปกรณ์
โดยไม่ต้องมีการรับส่งข้อมูลไปยังอุปกรณ์
หลังจาก SYNC
เริ่มต้นสำหรับอุปกรณ์แล้ว แพลตฟอร์มจะส่ง Intent QUERY
ที่รวบรวมสถานะของอุปกรณ์เพื่อป้อนข้อมูลใน Home Graph
หลังจากนั้น Home Graph จะจัดเก็บเฉพาะสถานะที่ส่งพร้อมกับ Report State
เมื่อเรียกใช้ Report State โปรดระบุข้อมูลสถานะที่สมบูรณ์
สำหรับลักษณะที่กำหนด Home Graph จะอัปเดตสถานะในลักษณะ
ต่อลักษณะ และเขียนทับข้อมูลทั้งหมดของลักษณะนั้นเมื่อมีการเรียกใช้ Report State
เช่น หากคุณรายงาน
สถานะสำหรับลักษณะStartStop เพย์โหลด
ต้องมีค่าสำหรับทั้ง isRunning
และ isPaused
เริ่มต้นใช้งาน
หากต้องการใช้ Report State ให้ทำตามขั้นตอนต่อไปนี้
เปิดใช้ Google HomeGraph API
-
ใน Google Cloud Console ให้ไปที่หน้า HomeGraph API
ไปที่หน้า HomeGraph API - เลือกโปรเจ็กต์ที่ตรงกับsmart homeรหัสโปรเจ็กต์
- คลิกเปิดใช้
สร้างคีย์บัญชีบริการ
ทำตามวิธีการต่อไปนี้เพื่อสร้างคีย์บัญชีบริการจาก Google Cloud Console
-
ใน Google Cloud Console ให้ไปที่หน้าบัญชีบริการ
ไปที่หน้าบัญชีบริการคุณอาจต้องเลือกโปรเจ็กต์ก่อนระบบจึงจะนำคุณไปยังหน้าบัญชีบริการ
คลิก
สร้างบัญชีบริการป้อนชื่อในช่องชื่อบัญชีบริการ
ป้อนรหัสในช่องรหัสบัญชีบริการ
ป้อนคำอธิบายในช่องคำอธิบายบัญชีบริการ
คลิกสร้างและต่อไป
จากเมนูแบบเลื่อนลงบทบาท ให้เลือกบัญชีบริการ > ผู้สร้างโทเค็นข้อมูลประจำตัว OpenID Connect ของบัญชีบริการ
คลิกต่อไป
คลิกเสร็จสิ้น
เลือกบัญชีบริการที่คุณเพิ่งสร้างจากรายการบัญชีบริการ แล้วเลือกจัดการคีย์จากเมนู
การดำเนินการเลือกเพิ่มคีย์ > สร้างคีย์ใหม่
สำหรับประเภทคีย์ ให้เลือกตัวเลือก JSON
คลิกสร้าง ระบบจะดาวน์โหลดไฟล์ JSON ที่มีคีย์ ลงในคอมพิวเตอร์
เรียก API
เลือกตัวเลือกจากแท็บด้านล่าง
HTTP
Home Graph มีปลายทาง HTTP
- ใช้ไฟล์ JSON ของบัญชีบริการที่ดาวน์โหลดมาเพื่อสร้าง JSON Web Token (JWT) ดูข้อมูลเพิ่มเติมได้ที่ การตรวจสอบสิทธิ์โดยใช้บัญชีบริการ
- รับโทเค็นเพื่อการเข้าถึง OAuth 2.0 ที่มี
https://www.googleapis.com/auth/homegraph
โดยใช้ oauth2l - สร้างคำขอ JSON ด้วย
agentUserId
ต่อไปนี้คือตัวอย่างคำขอ JSON สำหรับรายงานสถานะและการแจ้งเตือน - รวม JSON ของรายงานสถานะและการแจ้งเตือนกับโทเค็นในคำขอ HTTP POST
ไปยังปลายทาง Google Home Graph ตัวอย่างวิธีส่งคำขอในบรรทัดคำสั่งโดยใช้
curl
เพื่อเป็นการทดสอบมีดังนี้
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "requestId": "123ABC", "agentUserId": "user-123", "payload": { "devices": { "states": { "light-123": { "on": true } } } } }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
gRPC
Home Graph มีปลายทาง gRPC
- รับคำจำกัดความของบริการ Protocol Buffers สำหรับ Home Graph API
- ทำตามเอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์ gRPC เพื่อสร้างต้นขั้วไคลเอ็นต์สำหรับภาษาที่รองรับ
- เรียกใช้เมธอด ReportStateAndNotification
Node.js
ไคลเอ็นต์ Node.js ของ Google APIs มีการเชื่อมโยงสำหรับ Home Graph API
- เริ่มต้นบริการ
google.homegraph
โดยใช้ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน - เรียกใช้เมธอด
reportStateAndNotification
ด้วย ReportStateAndNotificationRequest โดยจะแสดงPromise
พร้อม ReportStateAndNotificationResponse
const homegraphClient = homegraph({ version: 'v1', auth: new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/homegraph' }) }); const res = await homegraphClient.devices.reportStateAndNotification({ requestBody: { agentUserId: 'PLACEHOLDER-USER-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { states: { "PLACEHOLDER-DEVICE-ID": { on: true } } } } } });
Java
ไลบรารีของไคลเอ็นต์ HomeGraph API สำหรับ Java มีการเชื่อมโยงสำหรับ Home Graph API
- เริ่มต้น
HomeGraphApiService
โดยใช้ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน - เรียกใช้เมธอด
reportStateAndNotification
ด้วยReportStateAndNotificationRequest
โดยจะแสดงผลเป็นReportStateAndNotificationResponse
// Get Application Default credentials. GoogleCredentials credentials = GoogleCredentials.getApplicationDefault() .createScoped(List.of("https://www.googleapis.com/auth/homegraph")); // Create Home Graph service client. HomeGraphService homegraphService = new HomeGraphService.Builder( GoogleNetHttpTransport.newTrustedTransport(), GsonFactory.getDefaultInstance(), new HttpCredentialsAdapter(credentials)) .setApplicationName("HomeGraphExample/1.0") .build(); // Build device state payload. Map<?, ?> states = Map.of("on", true); // Report device state. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states)))); homegraphService.devices().reportStateAndNotification(request); }
สถานะรายงานการทดสอบ
คุณต้องทดสอบ Report State เพื่อให้Cloud-to-cloudพร้อมสำหรับการ รับรอง
เราขอแนะนำให้ใช้Home Graphเครื่องมือ Viewer ซึ่งเป็นเว็บแอปแบบสแตนด์อโลนที่ไม่ต้องดาวน์โหลดหรือติดตั้งใช้งาน
Report State แดชบอร์ดยังคงใช้งานได้ แต่เราได้เลิกใช้งานแล้วและไม่มีการรองรับอีกต่อไป
แดชบอร์ดรายงานสถานะ
ข้อกำหนดเบื้องต้น
ก่อนที่จะทดสอบการผสานรวม Cloud-to-cloud ได้ คุณต้องมีคีย์บัญชีบริการและ agentUserId
หากคุณมีคีย์บัญชีบริการอยู่แล้ว ให้agentUserId
ดูติดตั้งใช้งานแดชบอร์ดReport State
ติดตั้งใช้งานแดชบอร์ดรายงานสถานะ
เมื่อมีคีย์บัญชีบริการและรหัสผู้ใช้ตัวแทนสำหรับโปรเจ็กต์แล้ว
ให้ดาวน์โหลดและติดตั้งใช้งานเวอร์ชันล่าสุดจาก
Report State
แดชบอร์ด
เมื่อดาวน์โหลดเวอร์ชันล่าสุดแล้ว ให้ทำตามวิธีการจากไฟล์ README.MD
ที่รวมไว้
หลังจากติดตั้งใช้งานแดชบอร์ด Report State แล้ว ให้เข้าถึง แดชบอร์ดจาก URL ต่อไปนี้ (แทนที่ your_project_id ด้วยรหัสโปรเจ็กต์ ของคุณ)
http://<your-project-id>.appspot.com
ในแดชบอร์ด ให้ทำดังนี้
- เลือกไฟล์คีย์บัญชี
- เพิ่ม agentUserId
จากนั้นคลิกแสดงรายการ
อุปกรณ์ทั้งหมดของคุณจะแสดงอยู่ในรายการ เมื่อระบบสร้างรายการแล้ว คุณจะใช้ปุ่มรีเฟรชเพื่ออัปเดตสถานะอุปกรณ์ได้ หากมีการเปลี่ยนแปลงสถานะของอุปกรณ์ แถวจะไฮไลต์เป็นสีเขียว
รายงานความคลาดเคลื่อนของสถานะ
ความแม่นยำของสถานะรายงานตามคำค้นหาจะวัดว่าสถานะรายงานล่าสุด ของอุปกรณ์ตรงกับสถานะของอุปกรณ์เมื่อผู้ใช้ค้นหามากน้อยเพียงใด ค่านี้คาดว่าจะอยู่ที่ 99.5%
การตอบกลับข้อผิดพลาด
คุณอาจได้รับการตอบกลับที่แสดงข้อผิดพลาดอย่างใดอย่างหนึ่งต่อไปนี้เมื่อเรียกใช้ Report State การตอบกลับเหล่านี้อยู่ในรูปแบบรหัสสถานะ HTTP
400 Bad Request
- เซิร์ฟเวอร์ไม่สามารถประมวลผลคำขอที่ไคลเอ็นต์ส่งมาเนื่องจากไวยากรณ์ไม่ถูกต้อง สาเหตุที่พบบ่อย ได้แก่ JSON ที่มีรูปแบบไม่ถูกต้อง หรือการใช้null
แทน "" สำหรับค่าสตริง404 Not Found
- ไม่พบทรัพยากรที่ขอ แต่อาจพร้อมใช้งานในอนาคต โดยปกติแล้วข้อความนี้จะหมายความว่าเรา ไม่พบอุปกรณ์ที่ขอ นอกจากนี้ยังอาจหมายความว่าบัญชีผู้ใช้ ไม่ได้ลิงก์กับ Google หรือเราได้รับagentUserId
ที่ไม่ถูกต้อง ตรวจสอบว่าagentUserId
ตรงกับค่าที่ระบุในการตอบกลับ SYNC และคุณได้จัดการเจตนา DISCONNECT อย่างถูกต้อง
การรายงานสถานะออนไลน์และออฟไลน์
เมื่ออุปกรณ์ออฟไลน์ คุณควรรายงาน <code{"online": code="" dir="ltr" false}<="" translate="no"> ไปยัง รายงานสถานะ ภายใน 5 นาทีหลังจาก พฤติกรรมของอุปกรณ์ ในทางกลับกัน เมื่ออุปกรณ์กลับมาอยู่ในสถานะออนไลน์ คุณควรรายงาน <code{"online": code="" dir="ltr" translate="no" true}<=""> ไปยังรายงานสถานะภายใน 5 นาทีหลังจากพฤติกรรมของอุปกรณ์ เมื่อใดก็ตามที่อุปกรณ์กลับมาออนไลน์ พาร์ทเนอร์ควรรายงานสถานะปัจจุบันทั้งหมดของอุปกรณ์โดยใช้reportStateAndNotification
API
ตัวอย่างนี้แสดงว่าlight
ประเภทอุปกรณ์ออนไลน์อยู่ และรายงาน
สถานะอุปกรณ์ปัจจุบันทั้งหมด
"requestId": "test-request-id",
"agentUserId": "agent-user-1",
"payload":{
"devices": {
"states": {
"device-id-1": {
"brightness": 65,
"on": true,
"online": true
}
"notifications": {},
}
}
}