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 เพิ่มความสว่างให้ห้องนั่งเล่นของฉัน ทําให้ต้องแก้ปัญหาความตั้งใจ 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 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
- รับคําจํากัดความของบริการบัฟเฟอร์โปรโตคอลสําหรับ Home Graph API
- ทําตามเอกสารสําหรับนักพัฒนาซอฟต์แวร์ gRPC เพื่อสร้างต้นขั้วไคลเอ็นต์สําหรับภาษาที่รองรับ
- เรียกเมธอด ReportStateAndNotification
Node.js
ไคลเอ็นต์ Google API 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หน้าแดชบอร์ด
ทําให้หน้าแดชบอร์ดสถานะรายงานใช้งานได้
เมื่อมีคีย์บัญชีบริการและ User Agent สําหรับโปรเจ็กต์แล้ว ให้ดาวน์โหลดและติดตั้งเวอร์ชันล่าสุดจาก Report State
Dashboard
เมื่อดาวน์โหลดเวอร์ชันล่าสุดแล้ว ให้ทําตามวิธีการจากไฟล์ 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 อย่างถูกต้อง