การแก้ปัญหาข้อผิดพลาดในการผสานรวม

ระบบคลาวด์สู่ระบบคลาวด์    Matter

Google Cloud มีเครื่องมือที่จะช่วยคุณตรวจสอบความเสถียรของโปรเจ็กต์ด้วย Google Cloud Monitoring และแก้ไขข้อบกพร่องด้วยบันทึกข้อผิดพลาดของ Google Cloud Logging เมื่อใดก็ตามที่เกิดความล้มเหลวเมื่อดำเนินการตามความตั้งใจของผู้ใช้ไปป์ไลน์ Google Home Analytics จะบันทึกความล้มเหลวนั้นในเมตริกของคุณ และเผยแพร่บันทึกข้อผิดพลาดในบันทึกโปรเจ็กต์

การแก้ปัญหามี 2 ขั้นตอนดังนี้

  1. ตรวจสอบสถานะของโปรเจ็กต์ด้วยเมตริกสมาร์ทโฮม
  2. ตรวจสอบปัญหาโดยดูคำอธิบายข้อผิดพลาดโดยละเอียดในบันทึกข้อผิดพลาด

กระบวนการนี้คล้ายกับการผสานรวมในเครื่องโดยใช้ Local Home SDK เมื่อคุณเชี่ยวชาญขั้นตอนการแก้ปัญหาแล้ว คุณจะสลับไปมาระหว่างเมตริกและบันทึกได้อย่างง่ายดายเพื่อรับข้อมูลเชิงลึกเกี่ยวกับข้อผิดพลาด

คุณสามารถทดสอบการดำเนินการได้โดยแชร์กับผู้ใช้รายอื่น (ไม่บังคับ) ตรวจสอบว่าได้จัดการข้อผิดพลาดและข้อยกเว้นอย่างเหมาะสม

ข้อผิดพลาดในการตรวจสอบ

คุณสามารถใช้ Google Cloud Monitoring dashboard เพื่อเข้าถึงเมตริกของโปรเจ็กต์ได้ แผนภูมิสำคัญบางรายการที่มีประโยชน์อย่างยิ่งสำหรับการตรวจสอบคุณภาพและการแก้ไขข้อบกพร่องมีดังนี้

  • แผนภูมิอัตราความสำเร็จเป็นแผนภูมิแรกที่ควรเริ่มดูเมื่อคุณตรวจสอบความน่าเชื่อถือของโปรเจ็กต์ การลดลงในแผนภูมินี้อาจบ่งบอกถึงการหยุดทำงานของฐานผู้ใช้บางส่วนหรือทั้งหมด เราขอแนะนำให้ตรวจสอบแผนภูมินี้อย่างใกล้ชิดเพื่อหาความผิดปกติหลังจากการเปลี่ยนแปลงหรืออัปเดตโปรเจ็กต์แต่ละครั้ง
  • แผนภูมิเวลาในการตอบสนองเปอร์เซ็นไทล์ที่ 95 เป็นตัวบ่งชี้ที่สำคัญว่าการผสานรวม Cloud-to-cloud ทำงานอย่างไรสำหรับผู้ใช้ ความผันผวนอย่างฉับพลันในแผนภูมินี้อาจบ่งชี้ว่าระบบของคุณอาจไม่สามารถตอบสนองคำขอได้ทัน เราขอแนะนำให้ตรวจสอบแผนภูมินี้เป็นระยะๆ เพื่อดูพฤติกรรมที่ไม่คาดคิด
  • แผนภูมิรายละเอียดข้อผิดพลาดมีประโยชน์มากที่สุดเมื่อต้องแก้ปัญหาเกี่ยวกับการผสานรวม สำหรับข้อผิดพลาดทุกรายการที่ไฮไลต์ในแผนภูมิเปอร์เซ็นต์ความสำเร็จ รหัสข้อผิดพลาดจะแสดงในรายละเอียดข้อผิดพลาด คุณสามารถดูข้อผิดพลาดที่ Google Home platform แจ้งไว้ และวิธีแก้ปัญหาได้ในตารางด้านล่าง

รหัสข้อผิดพลาดที่พบบ่อยของแพลตฟอร์ม

ต่อไปนี้คือรหัสข้อผิดพลาดที่พบบ่อยซึ่งคุณอาจเห็นในบันทึกของโปรเจ็กต์เพื่อระบุปัญหาที่ Google Home platform ตรวจพบ ดูข้อมูลการแก้ปัญหาได้ในตารางต่อไปนี้ ดูรายการรหัสข้อผิดพลาดทั้งหมดได้ที่ข้อผิดพลาดและข้อยกเว้น

รหัสข้อผิดพลาด คำอธิบาย พาร์ทเนอร์ดำเนินการได้
AGENT_ISSUE เกิดปัญหาทั่วไปกับตัวแทนระบบคลาวด์ของพาร์ทเนอร์

ตรวจสอบข้อยกเว้นหรือข้อขัดข้องที่ไม่ได้จัดการในบันทึกการดำเนินการตามคำสั่งซื้อ 		ใช่
AGENT_UNAVAILABLE_ERROR Google เข้าถึง URL การดำเนินการตามคำสั่งซื้อของพาร์ทเนอร์ไม่ได้

ตรวจสอบว่าเซิร์ฟเวอร์ออนไลน์อยู่ ไฟร์วอลล์ไม่ได้บล็อก Google และ URL ถูกต้อง 		ใช่
COMMAND_FAILED เกิดข้อผิดพลาดทั่วไปในระหว่างการดำเนินการคำสั่ง

ตรวจสอบบันทึกการดำเนินการตามคำสั่งซื้อเพื่อหา requestId ที่เฉพาะเจาะจงเพื่อหาสาเหตุของปัญหา 		ใช่
EXECUTION_BACKEND_FAILURE_URL_ERROR Google ได้รับข้อผิดพลาด HTTP 4xx (นอกเหนือจาก 401) จากการดำเนินการตามคำสั่งซื้อของคุณ

ตรวจสอบบันทึกของเว็บเซิร์ฟเวอร์เพื่อหาการตอบกลับ 403, 404 หรือ 400 		ใช่
EXECUTION_BACKEND_FAILURE_URL_TIMEOUT คำขอของ Google หมดเวลาเมื่อพยายามเข้าถึงบริการของคุณ

ตรวจสอบว่าบริการของคุณออนไลน์อยู่ ยอมรับการเชื่อมต่อ และไม่เกินความจุ นอกจากนี้ ให้ตรวจสอบว่าอุปกรณ์เป้าหมายเปิดอยู่ ออนไลน์ และซิงค์แล้ว 		ใช่
EXECUTION_BACKEND_FAILURE_URL_ROBOTED URL การดำเนินการตามคำสั่งซื้อถูกบล็อกโดย robots.txt หรือตัวกรองความปลอดภัย

ตรวจสอบว่า Crawler/บริการของ Google เข้าถึงปลายทางการดำเนินการตามคำสั่งซื้อได้ 		ใช่
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE Google ได้รับข้อผิดพลาด HTTP 5xx จากบริการ Fulfillment ของคุณ

ตรวจสอบว่าบริการ URL ปลายทางมีความเสถียร ถูกต้อง และเข้าถึงได้แบบสาธารณะ รวมถึงบริการทำงานอยู่ ใช้ requestId ใน Google Cloud Logging เพื่อตรวจสอบบันทึกบริการสมาร์ทโฮม เพิ่มการตรวจสอบประสิทธิภาพการทำงานและการลองจัดการอีกครั้ง ตรวจสอบข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ขัดข้อง การหมดเวลา หรือข้อผิดพลาดเกตเวย์ 502/503 		ใช่
EXECUTION_BAILOUT_INVALID_RESPONSE การตอบกลับ JSON มีรูปแบบไม่ถูกต้องจนต้องยกเลิกการประมวลผล

ใช้เครื่องมือตรวจสอบ JSON เพื่อให้แน่ใจว่าการตอบกลับเป็นไปตามสคีมา Intent อย่างเคร่งครัด 		ใช่
EXECUTION_GAL_BAD_3P_RESPONSE ลิงก์บัญชีไม่สำเร็จเนื่องจากรูปแบบในการตอบกลับโทเค็นไม่ถูกต้อง

ตรวจสอบว่ารูปแบบการตอบกลับของเซิร์ฟเวอร์ OAuth ตรงกับข้อกำหนดของ Google 		ใช่
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES บัญชีของผู้ใช้ไม่มีสิทธิ์ที่จำเป็นสำหรับการดำเนินการนี้

ตรวจสอบขอบเขตที่ขอระหว่าง OAuth และตรวจสอบว่าตรงกับลักษณะที่จำเป็น 		ใช่
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P ระบบคลาวด์ของพาร์ทเนอร์ระบุว่าผู้ใช้ยกเลิกการลิงก์บัญชีแล้ว

ตรวจสอบว่าการแมป agentUserId มีความเสถียรและไม่ได้ถูกล้างออก 		ใช่
EXECUTION_GAL_NOT_FOUND โทเค็นการเข้าถึงและโทเค็นการรีเฟรชของผู้ใช้ที่จัดเก็บไว้ใน Google ไม่ถูกต้องหรือไม่สามารถรีเฟรชได้ ซึ่งทำให้ไม่สามารถตรวจสอบสิทธิ์และเข้าถึงบริการของพาร์ทเนอร์ได้

ตรวจสอบว่าโทเค็นยังคงถูกต้องและซิงค์อยู่ จัดการการเปลี่ยนแปลงสถานะบัญชีอย่างเหมาะสม และกำหนดให้ผู้ใช้ลิงก์บัญชีอีกครั้งหากยืนยันแล้วว่าโทเค็นถูกเพิกถอน
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P การผสานรวมอยู่ในสถานะอ่านอย่างเดียวในฝั่งพาร์ทเนอร์

ตรวจสอบว่าบัญชีของผู้ใช้ถูกระงับหรืออยู่ในโหมดการบำรุงรักษาแบบ "ดูอย่างเดียว" หรือไม่ 		ใช่
EXECUTION_GAL_UNLINKED_BY_3P บริการของบุคคลที่สามได้ยกเลิกการลิงก์บัญชีในเชิงรุก

ตรวจสอบสาเหตุที่ผู้ใช้ถูกตัดการเชื่อมต่อ (เช่น การรีเซ็ตเพื่อความปลอดภัย) ตรวจสอบว่าเซิร์ฟเวอร์ OAuth ของพาร์ทเนอร์ตอบสนองต่อคำขอ refresh_token ของ Google อย่างถูกต้องเพื่อออกโทเค็นเพื่อการเข้าถึงใหม่อย่างราบรื่น 		ใช่
EXECUTION_INVALID_JSON Google แยกวิเคราะห์เพย์โหลดการตอบกลับ JSON ไม่ได้

ตรวจสอบข้อผิดพลาดทางไวยากรณ์ วงเล็บที่ขาดหายไป หรืออักขระที่ไม่ถูกต้องในการตอบกลับ 		ใช่
INVALID_AUTH_TOKEN Google ได้รับรหัสข้อผิดพลาด HTTP 401 จากบริการของคุณ

โทเค็นเพื่อการเข้าถึงยังไม่หมดอายุ แต่บริการของคุณทำให้โทเค็นใช้งานไม่ได้ ใช้ requestId ใน Google Cloud Logging เพื่อตรวจสอบบันทึกบริการสมาร์ทโฮม
INVALID_JSON โครงสร้างการตอบกลับไม่ถูกต้อง (เช่น ไม่มีช่องที่จำเป็น)

ตรวจสอบการตอบกลับของคุณกับสคีมา JSON ของ Intent 		ใช่
MALFORMED_JSON โครงสร้าง JSON เสียหาย (เช่น สตริงหรือออบเจ็กต์ที่ไม่ได้ปิด)

ตรวจสอบว่า Fulfillment ใช้ไลบรารี JSON มาตรฐานเพื่อจัดเรียงการตอบกลับเป็นอนุกรม 		ใช่
NOT_IMPLEMENTED พาร์ทเนอร์ยังไม่ได้ใช้ Intent หรือลักษณะที่ขอ

รวมเฉพาะลักษณะในคำตอบ SYNC ที่คุณได้ติดตั้งใช้งานอย่างสมบูรณ์แล้ว 		ใช่
OPEN_AUTH_FAILURE โทเค็นเพื่อการเข้าถึงของผู้ใช้หมดอายุและ Google ไม่สามารถรีเฟรชได้ หรือ Google ได้รับรหัสข้อผิดพลาด HTTP 401 จากบริการของคุณ

หากคุณเห็นอัตราของรหัสนี้เพิ่มขึ้น ให้ตรวจสอบว่าคุณเห็นอัตราข้อผิดพลาดที่เกี่ยวข้องกับ Intent ของสมาร์ทโฮมหรือคำขอโทเค็นการรีเฟรชเพิ่มขึ้นด้วยหรือไม่
PARTNER_RESPONSE_INVALID_ERROR_CODE สตริง errorCode ที่แสดงผลไม่อยู่ในรายการที่ Google รองรับ

แมปข้อผิดพลาดภายในกับรายการข้อผิดพลาดอย่างเป็นทางการ 		ใช่
PARTNER_RESPONSE_INVALID_PAYLOAD ฟิลด์ payload ในการตอบกลับไม่ใช่ออบเจ็กต์ JSON ที่ถูกต้อง

ยืนยันโครงสร้างรูทของการตอบสนองของ Fulfillment 		ใช่
PARTNER_RESPONSE_INVALID_STATUS การตอบกลับ status ไม่ใช่ SUCCESS, ERROR หรือ OFFLINE

ตรวจสอบว่าผลลัพธ์ของอุปกรณ์ทุกรายการในการตอบกลับมีสตริงสถานะที่ถูกต้อง 		ใช่
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES การตอบกลับไม่มีผลลัพธ์สำหรับคำสั่ง/อุปกรณ์ที่ขอทั้งหมด

ตรวจสอบความถูกต้องของโครงสร้างการตอบกลับกับเอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์ Google Home ตรวจสอบว่าการตอบกลับไม่ได้ถูกตัดออกหรือแสดงเนื้อหาที่ว่างเปล่าเนื่องจากข้อผิดพลาดภายในเซิร์ฟเวอร์ ทุกรายการในอาร์เรย์ commands ของคำขอต้องมีรายการการตอบกลับที่สอดคล้องกัน 		ใช่
PARTNER_RESPONSE_MISSING_DEVICE ระบบละเว้นอุปกรณ์ที่เฉพาะเจาะจงซึ่ง Google ขอจากการตอบกลับ

ตรวจสอบว่าการตอบกลับมี ID ทุกรายการที่ระบุไว้ในเพย์โหลดคำขอ 		ใช่
PARTNER_RESPONSE_MISSING_PAYLOAD การตอบกลับไม่มีช่อง payload ที่จำเป็น

ตรวจสอบว่าออบเจ็กต์ JSON ระดับบนสุดมีคีย์ payload 		ใช่
PARTNER_RESPONSE_NOT_OBJECT แยกวิเคราะห์การตอบกลับทั้งหมดเป็นออบเจ็กต์ JSON ไม่ได้

ตรวจสอบอักขระต่อท้ายหรือเนื้อหาที่ไม่ใช่ JSON ในเนื้อความของการตอบกลับ HTTP ตรวจสอบว่า payload.commands[] เป็นออบเจ็กต์ JSON ที่เหมาะสมซึ่งมีรหัส สถานะ และสถานะที่ไม่บังคับ 		ใช่
REQUEST_ID_NOT_FOUND Google ไม่พบรหัสติดตามภายในสําหรับคําขอ

โดยปกติแล้วจะเป็นข้อผิดพลาดภายในแพลตฟอร์ม ให้ตรวจสอบการเพิ่มขึ้นอย่างฉับพลันและติดต่อทีมสนับสนุน 		ใช่
RESOURCE_UNAVAILABLE ทรัพยากรที่ขอ (อุปกรณ์หรือลักษณะ) ไม่พร้อมใช้งาน

ตรวจสอบว่าอุปกรณ์ "ไม่ว่าง" หรือถูกปิดใช้ชั่วคราวหรือไม่ 		ใช่
RESPONSE_TIMEOUT บริการ Fulfillment ไม่ตอบสนองภายใน 9 วินาที

เพิ่มประสิทธิภาพเวลาในการตอบสนองของแบ็กเอนด์ ตรวจสอบการค้นหา DB ที่ช้าหรือความล่าช้าของเครือข่ายระดับภูมิภาค 		ใช่
RESPONSE_UNAVAILABLE ไม่ได้รับการตอบกลับจาก URL การดำเนินการตามคำสั่งซื้อของพาร์ทเนอร์

ตรวจสอบว่าบริการทำงานอยู่และปลายทางไม่ขัดข้อง 		ใช่
TIMEOUT เกิดการหมดเวลาทั่วไปขณะประมวลผล Intent

ตรวจสอบบันทึกเพื่อดูการหมดเวลาของบริการภายในระหว่างระบบคลาวด์และฮับอุปกรณ์ 		ใช่

ข้อมูลบันทึกการค้นหา

เมื่อคุณตรวจสอบการผสานรวมโดยใช้เมตริกได้อย่างคล่องแคล่วแล้ว ขั้นตอนถัดไปคือการแก้ปัญหาข้อผิดพลาดที่เฉพาะเจาะจงโดยใช้ Cloud Logging บันทึกข้อผิดพลาดคือรายการที่คล้ายกับ JSON ซึ่งมีช่องที่มีข้อมูลที่เป็นประโยชน์ เช่น เวลา รหัสข้อผิดพลาด และรายละเอียดเกี่ยวกับ Intent ของสมาร์ทโฮมต้นทาง

Google Cloud มีหลายระบบที่ส่งบันทึกไปยังโปรเจ็กต์ของคุณตลอดเวลา คุณต้องเขียนคำค้นหาเพื่อกรองบันทึกและค้นหาบันทึกที่ต้องการ การค้นหาอาจอิงตามช่วงเวลา ทรัพยากร ความรุนแรงของบันทึก หรือรายการที่กำหนดเอง

บันทึกการค้นหาในระบบคลาวด์

คุณสามารถใช้ปุ่มการค้นหาเพื่อช่วยสร้างตัวกรองที่กำหนดเองได้

สร้างการค้นหาบันทึกในระบบคลาวด์

หากต้องการระบุช่วงเวลา ให้คลิกปุ่มเลือกช่วงเวลา แล้วเลือกตัวเลือกที่มีให้ ซึ่งจะกรองบันทึกและแสดงบันทึกที่เกิดขึ้นในช่วงเวลาที่เลือก

หากต้องการระบุทรัพยากร ให้คลิกเมนูแบบเลื่อนลงทรัพยากร แล้วเลือกโปรเจ็กต์การดำเนินการของ Google Assistant ซึ่งจะเพิ่มตัวกรองในคำค้นหาเพื่อแสดงบันทึกที่มาจากโปรเจ็กต์ของคุณ

ใช้ปุ่มความรุนแรงเพื่อกรองตามฉุกเฉิน ข้อมูล แก้ไขข้อบกพร่อง และระดับความรุนแรงอื่นๆ ของบันทึก

นอกจากนี้ คุณยังใช้ช่องการค้นหาใน Logs Explorer เพื่อป้อนรายการที่กำหนดเองได้ด้วย เครื่องมือค้นหาที่ช่องนี้ใช้รองรับทั้งการค้นหาพื้นฐาน เช่น การจับคู่สตริง และการค้นหาประเภทขั้นสูงอื่นๆ ซึ่งรวมถึงตัวเปรียบเทียบ (<, >=, !=) และโอเปอเรเตอร์บูลีน (AND, OR, NOT)

ตัวอย่างเช่น รายการที่กำหนดเองด้านล่างจะแสดงข้อผิดพลาดที่มาจากประเภทอุปกรณ์ LIGHT

resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"

ไปที่คลังการค้นหาเพื่อดูตัวอย่างเพิ่มเติมสำหรับการค้นหาบันทึกอย่างมีประสิทธิภาพ

การทดสอบการแก้ไข

เมื่อระบุข้อผิดพลาดและใช้การอัปเดตเพื่อแก้ไขแล้ว เราขอแนะนำให้ทดสอบการแก้ไขอย่างละเอียดด้วย Google Home Test Suite เรามีคู่มือผู้ใช้เกี่ยวกับวิธีใช้ Test Suite ซึ่งจะแนะนำวิธีทดสอบการเปลี่ยนแปลงอย่างมีประสิทธิภาพ

แหล่งข้อมูลการเรียนรู้

เอกสารนี้แสดงขั้นตอนการแก้ปัญหาข้อผิดพลาดในการดำเนินการสำหรับสมาร์ทโฮม นอกจากนี้ คุณยังดูข้อมูลเพิ่มเติมเกี่ยวกับการแก้ไขข้อบกพร่องได้ที่ Codelab ของเรา

ก่อนหน้า
Cloud Logging