ทั่วไป
ถาม: เราควรใช้งานโครงสร้างพื้นฐานการจัดการคำสั่งซื้อแบบคลาวด์ต่อคลาวด์ที่ใดและด้วยภาษาใด
ตอบ: ตราบใดที่โครงสร้างพื้นฐานรองรับ SSL (TLS) สมัยใหม่และ OAuth 2.0 คุณก็สามารถใช้งานโครงสร้างพื้นฐานบนแพลตฟอร์มใดก็ได้และด้วยภาษาใดก็ได้ตามที่ต้องการ เราขอแนะนำให้คุณนำไปใช้งานใกล้กับโครงสร้างพื้นฐานอื่นๆ มากที่สุดเท่าที่จะเป็นไปได้ เพื่อปรับปรุงความน่าเชื่อถือและลดเวลาในการตอบสนองสำหรับการดำเนินการไปยังอุปกรณ์ของผู้ใช้จริง
ถาม: รหัสอุปกรณ์ต้องไม่ซ้ำกันไหม
ตอบ: รหัสควรไม่ซ้ำกัน หากบริการของคุณไม่มีรหัสที่ไม่ซ้ำกัน รหัสเหล่านั้นต้องไม่ซ้ำกันอย่างน้อยในระดับผู้ใช้แต่ละราย ลองนึกภาพผู้ใช้ที่มีบ้านหลายหลัง โดยทั้ง 2 หลังมีการผสานรวมกับผู้ใช้รายเดียวกัน การขอให้เปิดไฟในบ้านหลังหนึ่งไม่ควรทำให้ไฟที่มีรหัสเดียวกันในบ้านอีกหลังเปิดขึ้น
ถาม: ชื่ออุปกรณ์ต้องไม่ซ้ำกันไหม
ตอบ: ชื่อไม่จำเป็นต้องไม่ซ้ำกัน แม้ว่าในอนาคตเราอาจสนับสนุนให้ผู้คนปรับปรุงการตั้งชื่อที่ไม่ดีหลังจากการตั้งค่าเพื่อประสบการณ์ของผู้ใช้ที่ดีขึ้น
ต่อไปนี้คือคำแนะนำในการตั้งชื่อแบบย่อ
- ชื่อควรเป็นสิ่งที่ผู้คนพูดได้จริง
- ระบบจะจดจำสตริงย่อย ดังนั้นหากคุณมี "ไฟสี acme" ระบบก็จะตอบกลับ "ไฟ acme" ด้วย
- เราขอแนะนำให้ใช้ทั้งชื่อที่สื่อความหมายสำหรับผลิตภัณฑ์และชื่อที่ผู้ใช้กำหนดเองอย่างน้อย 1 ชื่อ
- ผู้ใช้ไม่จำเป็นต้องตั้งชื่อห้องให้ไฟ เนื่องจากเรามีห้องให้ตั้งชื่ออยู่แล้ว โดยไฟควรมีชื่อที่ไม่ซ้ำกันต่อห้อง แต่สามารถใช้คำพหูพจน์เพื่อสั่งการทุกอย่างได้เสมอ (เช่น หลอดไฟ 2 หลอดในโคมไฟติดผนังของสำนักงานมีชื่อว่า "ไฟเหนือ" และ "ไฟตะวันออก" แต่สามารถสั่งการเป็น "ไฟ" ได้)
ถาม: สถานะอุปกรณ์ได้รับการอัปเดตบ่อยเพียงใด
ตอบ: ระบบจะดึงข้อมูลสถานะชั่วคราวเมื่อมีการดำเนินการ QUERY หรือ EXECUTE ซึ่งเป็นการดำเนินการที่ผู้ใช้เริ่มต้น หากผู้ใช้ถามว่า "ไฟเปิดอยู่ไหม" หรือต้องการเพิ่มความสว่างของไฟ เราจะต้องทำการค้นหาเพื่อดูสถานะปัจจุบัน
ถาม: เป็นไปได้ไหมที่จะอัปเดต Home Graph โดยตรงด้วยสถานะปัจจุบันของอุปกรณ์
ตอบ: ได้ ให้ใช้การเรียก API ของ Report State
การลิงก์บัญชีและ OAuth
ถาม: เราต้องทำการลิงก์บัญชีไหม
ตอบ: ใช่ คุณต้องทำการลิงก์บัญชีเพื่อเชื่อมต่ออุปกรณ์ของผู้ใช้กับบริการคลาวด์ของผู้ให้บริการ
ถาม: สำหรับ OAuth เราทำให้โทเค็นเพื่อการเข้าถึงหมดอายุทุกๆ 15.213 ชั่วโมง ซึ่งใช้ได้ไหม
ตอบ: ได้ แต่โปรดทดสอบด้วยเวลาหมดอายุที่ค่อนข้างสั้น เช่น 10-20 นาที ไคลเอ็นต์ OAuth ของเราควรจะรีเฟรชโทเค็นตามความจำเป็น และการทดสอบด้วยเวลาหมดอายุที่สั้นจะพิสูจน์ว่าการรีเฟรชโทเค็นทำงานได้
Intent
ถาม: SYNC เกิดขึ้นเมื่อใด
ตอบ: SYNC จะเกิดขึ้นทันทีหลังจาก OAuth เสร็จสมบูรณ์ และหลังจากมีการเรียก Request Sync
ถาม: เหตุใด SYNC จึงไม่ทำงาน
ตอบ: มีสาเหตุที่พบบ่อยหลายประการที่อาจทำให้เกิดข้อผิดพลาดนี้
คุณส่งประเภทอุปกรณ์ที่ไม่ถูกต้อง
- เช่น เราคาดหวัง
action.devices.types.LIGHTแต่คุณส่งaction.devices.types.Light
- เช่น เราคาดหวัง
คุณส่งประเภทอุปกรณ์ที่ไม่รองรับ
- เช่น คุณส่ง
action.devices.types.FLASHLIGHTซึ่งเป็นสิ่งที่เราไม่รองรับ
- เช่น คุณส่ง
คุณส่งช่องที่ไม่ถูกต้อง/ไม่รองรับ
- เช่น คุณมีช่องที่ไม่ได้อยู่ในข้อกำหนดของเรา
การตอบกลับ SYNC ของคุณมีปัญหาด้านการจัดรูปแบบอื่นๆ
- ตรวจสอบวงเล็บ!
คุณพบปัญหาเกี่ยวกับการลิงก์บัญชี
- โปรดตรวจสอบว่าคุณได้รับโทเค็นเพื่อการเข้าถึงที่ถูกต้องในส่วนหัวการตรวจสอบสิทธิ์ของคำขอ SYNC
คุณใช้เวลานานเกินไปในการตอบกลับคำขอ SYNC
- โปรดตรวจสอบว่าคุณตอบกลับคำขอ SYNC ภายใน 5 วินาที
ถาม: การตอบกลับ "รอดำเนินการ" ใช้ได้ไหม
ตอบ: เราต้องการการตอบกลับที่ระบุว่าสำเร็จ/ล้มเหลวมากกว่าการตอบกลับที่ระบุว่ารอดำเนินการ หากอุปกรณ์ของคุณพร้อมใช้งานแบบเรียลไทม์ โปรดติดต่อเราหากคุณรู้สึกว่าจำเป็นต้องมีการตอบกลับ "รอดำเนินการ" เนื่องจากเราทราบว่าอุปกรณ์บางอย่างที่ใช้พลังงานต่ำและไม่ใช่แบบเรียลไทม์อาจต้องมีการตอบกลับที่ระบุว่ารอดำเนินการและใช้โมเดลการดำเนินการแบบไม่พร้อมกัน
การทดสอบและการส่ง
ถาม: เราตั้งค่าสภาพแวดล้อมคลาวด์สำหรับการพัฒนาได้ไหม
ตอบ: ได้ คุณสามารถทดสอบสภาพแวดล้อมคลาวด์และการกำหนดค่าที่ยังไม่ได้เปิดตัวได้
ถาม: แอ็กชันของฉันไม่ปรากฏในส่วนระบบควบคุมอุปกรณ์ในบ้านของแอป Google Home เกิดอะไรขึ้น
ตอบ: ยืนยันว่าคุณเป็นนักพัฒนาแอปสำหรับโปรเจ็กต์นี้
Report State
ถาม: การใช้งาน Report State มีข้อกำหนดเบื้องต้นไหม
ตอบ: โปรเจ็กต์ต้องใช้ Smart Home API, รองรับ OAuth2 และต้องมีลักษณะที่ระบุสถานะที่จะรายงาน
ถาม: เราต้องรายงานสถานะของอุปกรณ์บ่อยเพียงใด
ตอบ: Google สนใจสถานะการเปลี่ยนผ่านและสถานะสุดท้าย อย่างไรก็ตาม หากมีการเปลี่ยนแปลงสถานะหลายครั้งในระยะเวลาอันสั้น (เช่น ผู้ใช้เปิดและปิดตู้เย็น 3 ครั้งใน 1 นาที หรือเลื่อนตัวหรี่ไฟ) เราต้องการเพียงสถานะสุดท้ายที่รายงาน
ถาม: ต้องส่งสถานะอุปกรณ์ทั้งหมดเมื่อทำการเรียก Report State ไหม
ตอบ: ระบบไม่รองรับการอัปเดตสถานะบางส่วน ดังนั้น Report State การเรียกควรมีข้อมูลทั้งหมดสำหรับ ลักษณะเฉพาะที่ได้รับการอัปเดตเสมอ หากลักษณะ 2 อย่างจะทำให้เกิดความไม่สอดคล้องกัน คุณควรรายงานลักษณะทั้ง 2 อย่างพร้อมกัน
ถาม: Google สามารถค้นหาอุปกรณ์ของฉันเพื่อรับสถานะ (เช่น โพลอุปกรณ์) ได้ไหม
ตอบ: นี่เป็นกลไกการทำงานสำรองที่เราไม่แนะนำ หากเราต้องกลับไปโพลอุปกรณ์ของผู้ใช้เหล่านั้นบ่อยๆ เราไม่สามารถรับประกันได้ว่าการโพลจะทำให้เกิดการโหลดเพิ่มเติมมากน้อยเพียงใด ความจำเป็นนี้มาจากพื้นผิวแสดงผลแบบใหม่ นอกจากปัญหาการโหลดที่ไม่ทราบแล้ว การโพลยังจะทำให้ผู้ใช้ได้รับประสบการณ์การใช้งานที่แย่ลงด้วย เรา เชื่อว่า Report State มีความสำคัญอย่างยิ่งต่อแพลตฟอร์ม
ถาม: ตอนนี้ลักษณะใดบ้างที่รองรับ Report State
ตอบ: ระบบรองรับลักษณะสาธารณะทั้งหมดที่มีสถานะที่เชื่อมโยง นอกจากนี้ คุณควรรายงานการเปลี่ยนแปลงสถานะออนไลน์ของอุปกรณ์ด้วย
โปรดทราบว่าฉากไม่มีสถานะ อย่างไรก็ตาม ฉากอาจทำให้สถานะของอุปกรณ์เปลี่ยนแปลง หากอุปกรณ์ใดก็ตามใน Google Home Graph มีการเปลี่ยนแปลงสถานะ คุณต้องรายงานการเปลี่ยนแปลงนั้นกลับมา
ถาม: Report State ต้องส่งการประทับเวลาไหม
ตอบ: เราไม่กำหนดให้ส่งการประทับเวลา โดยสถานะล่าสุดที่ส่งจะลบล้างการเรียกก่อนหน้า
ถาม: ฉันต้องรายงานสถานะแยกกันไหมหากส่งสถานะใน Query และ/หรือ Execute อยู่แล้ว
ตอบ: Home Graph จะจัดเก็บเฉพาะสถานะที่ส่งผ่าน Report State สถานะที่แสดงผลเป็นการตอบกลับ Intent EXECUTE และ QUERY จะใช้สำหรับการตอบกลับด้วยเสียงแก่ผู้ใช้เท่านั้นและจะไม่ได้รับการจัดเก็บ ดังนั้น คุณควรเรียก Report State แม้ว่าสถานะใหม่ของอุปกรณ์จะแสดงผลเป็นการตอบกลับ Intent EXECUTE หรือ QUERY แล้วก็ตาม
ถาม: จะเกิดอะไรขึ้นหากเราใช้งาน Report State ไม่เสร็จสมบูรณ์ภายในกำหนดเวลาที่กำหนด
ตอบ: การดำเนินการนี้จะทำให้ผู้ใช้ได้รับประสบการณ์การใช้งานที่แย่ลง เช่น ใน Google Home app (GHA) และพื้นผิวแสดงผล ซึ่งหมายความว่าระบบจะส่ง Intent QUERY จำนวนมากเพื่อโพลสถานะ และเราไม่สามารถรับประกันได้ว่าการโพลจะทำให้เกิดการโหลดเพิ่มเติมในคลาวด์ของพาร์ทเนอร์มากน้อยเพียงใด
ถาม: ฉันจะทดสอบการใช้งาน Report State ได้อย่างไร
ตอบ: ใช้ Home Graph Viewer ซึ่งเป็นเครื่องมือทดสอบแบบบริการตนเองที่แสดงสถานะอุปกรณ์ ปัจจุบันที่จัดเก็บไว้ใน Home Graph
ถาม: เราใช้ requestId แบบสุ่มสำหรับ Report State ได้ไหม
ตอบ: เราขอแนะนำให้พาร์ทเนอร์ใช้ requestId เดียวกันกับที่ได้รับจากคำขอ EXECUTE หาก Report State ถูกทริกเกอร์โดยคำขอ EXECUTE ไม่เช่นนั้นคุณก็ใช้ requestId แบบสุ่มได้
ถาม: หากผู้ใช้มีอุปกรณ์หลายเครื่องและอุปกรณ์เครื่องใดเครื่องหนึ่งมีการเปลี่ยนแปลงสถานะ เราต้องรายงานสถานะล่าสุดของอุปกรณ์ทั้งหมดไหม
ตอบ: ไม่ คุณต้องรายงานสถานะของอุปกรณ์เครื่องนั้นเท่านั้น
แนวทางปฏิบัติแนะนำ
ถาม: เวลาในการตอบสนองที่ยอมรับได้คือเท่าใด
ตอบ: เวลาในการตอบสนองที่น้อยกว่า 1, 000 มิลลิวินาทีถือเป็นเวลาที่เหมาะสม ส่วนเวลาในการตอบสนองระหว่าง 2-5 วินาทีถือว่าใช้ได้ หากเวลาในการตอบสนองของคุณอยู่ที่ประมาณ 5 วินาที โปรดติดต่อเรา
ถาม: ฉันจะทำให้ลำโพงที่สั่งงานด้วยเสียงตอบสนองอย่างเหมาะสมเมื่อออฟไลน์ได้อย่างไร
ตอบ: แสดงผลสถานะออฟไลน์สำหรับอุปกรณ์ที่ออฟไลน์ เราจะแสดงผล "ไม่พร้อมใช้งานในขณะนี้" เป็น TTS สำหรับข้อผิดพลาดนี้ ดูข้อมูลเพิ่มเติมได้ที่ ข้อผิดพลาดและข้อยกเว้น