Report State เป็นฟีเจอร์สำคัญที่ช่วยให้การดำเนินการ Home รายงานสถานะล่าสุดของอุปกรณ์ของผู้ใช้โดยอัตโนมัติกลับไปยัง Google Home Graph โดยไม่ต้องรอ Intent QUERY
Report State จะรายงานสถานะของอุปกรณ์ของผู้ใช้ให้ Google ทราบ agentUserId
ที่ระบุไว้ (ซึ่งส่งในคำขอ SYNC
เดิม) เมื่อ Google Assistant ต้องการดำเนินการที่ต้องอาศัยความเข้าใจสถานะปัจจุบันของอุปกรณ์ ก็เพียงแค่ค้นหาข้อมูลสถานะใน Home Graph แทนการออก Intent QUERY
ไปยังระบบคลาวด์ต่างๆ ของบุคคลที่สามก่อนกำหนด Intent EXECUTE
หากใช้ Report State เมื่อมีหลอดไฟจากผู้ให้บริการหลายรายในห้องนั่งเล่น คำสั่ง Ok Google เพิ่มความสว่างห้องนั่งเล่น ต้องแก้ไข Intent 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 ให้ไปที่หน้าสร้างคีย์บัญชีบริการ
ไปที่หน้าสร้างคีย์บัญชีบริการ - จากรายการบัญชีบริการ ให้เลือกบัญชีบริการใหม่
- ป้อนชื่อในช่องชื่อบัญชีบริการ
- ป้อนรหัสในช่องรหัสบัญชีบริการ
จากรายการบทบาท ให้เลือกบัญชีบริการ > ผู้สร้างโทเค็นบัญชีบริการ
สำหรับประเภทคีย์ ให้เลือกตัวเลือก JSON
- คลิกสร้าง ไฟล์ JSON ที่มีคีย์ที่ดาวน์โหลดลงในคอมพิวเตอร์
เรียกใช้ API
เลือกตัวเลือกจากแท็บด้านล่าง
HTTP
Home Graph มอบปลายทาง HTTP
- ใช้ไฟล์ JSON ของบัญชีบริการที่ดาวน์โหลดเพื่อสร้างโทเค็นเว็บ JSON (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
- ดูคำจำกัดความของบริการบัฟเฟอร์โปรโตคอลสำหรับ Home Graph API
- ทำตามเอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์ gRPC เพื่อสร้างสตับไคลเอ็นต์สำหรับภาษาที่รองรับ
- เรียกใช้เมธอด ReportStateAndNotification
Node.js
ไคลเอ็นต์ Google APIs Node.js มีการผูกสำหรับ 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 เพื่อเตรียมการดำเนินการให้พร้อมสำหรับการรับรอง
เราขอแนะนำให้ใช้เครื่องมือดู Home Graph ซึ่งเป็นเว็บแอปแบบสแตนด์อโลนที่ไม่ต้องดาวน์โหลดหรือทำให้ใช้งานได้
แดชบอร์ด Report State ยังคงใช้งานได้อยู่ แต่เลิกใช้งานแล้วและไม่มีการรองรับอีกต่อไป
หน้าแดชบอร์ดสถานะรายงาน
ข้อกำหนดเบื้องต้น
คุณต้องมีคีย์บัญชีบริการและ agentUserId
ก่อนจึงจะทดสอบการดำเนินการได้ หากคุณมีคีย์บัญชีบริการอยู่แล้ว และ agentUserId
โปรดดูทำให้แดชบอร์ด Report State ใช้งานได้
ทำให้หน้าแดชบอร์ดสถานะรายงานใช้งานได้
เมื่อคุณมีคีย์บัญชีบริการและรหัสผู้ใช้ตัวแทนสำหรับโปรเจ็กต์แล้ว ให้ดาวน์โหลดและทำให้เวอร์ชันล่าสุดใช้งานได้จากReport Stateหน้าแดชบอร์ด
เมื่อดาวน์โหลดเวอร์ชันล่าสุดแล้ว ให้ทำตามวิธีการจากไฟล์ README.MD
ที่รวมอยู่
หลังจากทำให้หน้าแดชบอร์ด Report State ใช้งานได้แล้ว ให้เข้าถึงหน้าแดชบอร์ดจาก URL ต่อไปนี้ (แทนที่ your_project_id ด้วยรหัสโปรเจ็กต์)
http://<your-project-id>.appspot.com
ดำเนินการต่อไปนี้ในหน้าแดชบอร์ด
- เลือกไฟล์คีย์บัญชี
- เพิ่ม agentUserId
จากนั้นคลิกรายการ
อุปกรณ์ทั้งหมดของคุณจะแสดงอยู่ในรายการ เมื่อสร้างรายการแล้ว คุณจะใช้ปุ่มรีเฟรชเพื่ออัปเดตสถานะอุปกรณ์ได้ หากมีการเปลี่ยนสถานะของอุปกรณ์ แถวจะไฮไลต์เป็นสีเขียว
การตอบกลับข้อผิดพลาด
คุณอาจได้รับการตอบกลับข้อผิดพลาดอย่างใดอย่างหนึ่งต่อไปนี้เมื่อโทรหา Report State การตอบสนองเหล่านี้มาในรูปแบบรหัสสถานะ HTTP
400 Bad Request
- เซิร์ฟเวอร์ไม่สามารถประมวลผลคำขอที่ส่งโดยไคลเอ็นต์เนื่องจากไวยากรณ์ไม่ถูกต้อง สาเหตุที่พบบ่อย ได้แก่ JSON ที่ผิดรูปแบบหรือใช้null
แทน "" สำหรับค่าสตริง404 Not Found
- ไม่พบทรัพยากรที่ขอแต่อาจใช้งานได้ในอนาคต ปกติแล้วจะหมายความว่าเรา ไม่พบอุปกรณ์ที่ขอ นอกจากนี้ยังอาจหมายความว่าบัญชีผู้ใช้ไม่ได้ลิงก์กับ Google หรือเราได้รับagentUserId
ที่ไม่ถูกต้อง ตรวจสอบว่าagentUserId
ตรงกับค่าที่ระบุไว้ในการตอบกลับ SYNC และคุณกำลังจัดการ Intent ของ DISCONNECT อย่างถูกต้อง