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
ไคลเอ็นต์ 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 เพื่อให้การดำเนินการของคุณพร้อมสำหรับการรับการรับรอง
ในการดำเนินการ เราขอแนะนำให้ใช้เครื่องมือดู 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 ของ ยกเลิกการเชื่อมต่อ อย่างถูกต้อง