ทั่วไป
ถาม: เราควรใช้งานโครงสร้างพื้นฐานการดำเนินการตามคำสั่งจากคลาวด์ถึงคลาวด์ที่ใดและด้วยภาษาใด
ตอบ: ตราบใดที่โครงสร้างพื้นฐานรองรับ 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 ภายใน 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 สำหรับข้อผิดพลาดนี้ ดูข้อมูลเพิ่มเติมได้ที่ ข้อผิดพลาดและข้อยกเว้น