Khắc phục lỗi tích hợp Matter

refresh_date: 2023-01-06

Google Cloud cung cấp cho bạn các công cụ để theo dõi độ tin cậy của dự án bằng Google Cloud Monitoring và gỡ lỗi bằng nhật ký lỗi Google Cloud Logging. Bất cứ khi nào xảy ra lỗi khi thực hiện ý định của người dùng, quy trình Google Home Analytics sẽ ghi lại lỗi đó trong các chỉ số của bạn và xuất bản nhật ký lỗi trong nhật ký dự án.

Có hai bước để khắc phục sự cố lỗi của bạn:

  1. Theo dõi trạng thái của dự án bằng các chỉ số về nhà thông minh.
  2. Điều tra vấn đề bằng cách kiểm tra nội dung mô tả chi tiết về lỗi trong nhật ký lỗi.

Lỗi giám sát

Bạn có thể sử dụng Google Cloud Monitoring dashboards để truy cập vào các chỉ số của dự án. Có một số biểu đồ chính đặc biệt hữu ích cho việc theo dõi chất lượng và gỡ lỗi:

  • Biểu đồ Tỷ lệ thành công là biểu đồ đầu tiên bạn nên xem khi theo dõi độ tin cậy của dự án. Sự sụt giảm trong biểu đồ này có thể cho thấy tình trạng ngừng hoạt động đối với một phần hoặc toàn bộ cơ sở người dùng của bạn. Bạn nên theo dõi chặt chẽ biểu đồ này để phát hiện mọi điểm bất thường sau mỗi lần thay đổi hoặc cập nhật dự án.
  • Biểu đồ Error Breakdown (Thông tin chi tiết về lỗi) là biểu đồ hữu ích nhất khi bạn cần khắc phục sự cố về các hoạt động tích hợp. Đối với mỗi lỗi được làm nổi bật trong biểu đồ tỷ lệ phần trăm thành công, một mã lỗi sẽ xuất hiện trong bảng chi tiết về lỗi. Bạn có thể xem các lỗi được Google Home platform (GHP) gắn cờ và cách khắc phục sự cố các lỗi đó trong bảng dưới đây.

Mã lỗi phổ biến của nền tảng

Dưới đây là một số mã lỗi thường gặp mà bạn có thể thấy trong nhật ký dự án để xác định các vấn đề mà GHP phát hiện được. Hãy tham khảo bảng sau để biết thông tin về cách khắc phục sự cố. Để xem danh sách đầy đủ các mã lỗi, hãy xem phần Lỗi và ngoại lệ.

Mã lỗi Mô tả Hành động của đối tác
AGENT_ISSUE Đã xảy ra vấn đề chung với tác nhân đám mây của đối tác.

Kiểm tra các trường hợp ngoại lệ hoặc sự cố chưa được xử lý trong nhật ký thực hiện. 		Có
AGENT_UNAVAILABLE_ERROR Google không thể truy cập vào URL thực hiện đơn hàng của đối tác.

Đảm bảo máy chủ của bạn có kết nối mạng, tường lửa không chặn Google và URL là chính xác. 		Có
COMMAND_FAILED Đã xảy ra lỗi chung trong quá trình thực thi lệnh.

Kiểm tra nhật ký thực hiện cho requestId cụ thể để tìm ra nguyên nhân gốc. 		Có
EXECUTION_BACKEND_FAILURE_URL_ERROR Google nhận được lỗi HTTP 4xx (không phải 401) từ phương thức thực hiện của bạn.

Kiểm tra nhật ký máy chủ web để tìm phản hồi 403, 404 hoặc 400. 		Có
EXECUTION_BACKEND_FAILURE_URL_TIMEOUT Yêu cầu của Google đã hết thời gian chờ khi cố gắng kết nối với dịch vụ của bạn.

Xác minh rằng dịch vụ của bạn đang hoạt động, chấp nhận kết nối và không vượt quá dung lượng. Ngoài ra, hãy xác minh rằng thiết bị mục tiêu đã bật nguồn, có kết nối mạng và đã đồng bộ hoá. 		Có
EXECUTION_BACKEND_FAILURE_URL_ROBOTED URL thực hiện bị tệp robots.txt hoặc bộ lọc bảo mật chặn.

Đảm bảo trình thu thập dữ liệu/dịch vụ của Google có thể truy cập vào điểm cuối thực hiện đơn hàng của bạn. 		Có
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE Google đã nhận được lỗi HTTP 5xx từ dịch vụ thực hiện đơn hàng của bạn.

Đảm bảo dịch vụ URL điểm cuối ổn định, chính xác và có thể truy cập công khai, dịch vụ đang chạy. Sử dụng requestId trong Google Cloud Logging để kiểm tra nhật ký dịch vụ nhà thông minh. Thêm quy trình kiểm tra tình trạng và xử lý thử lại. Điều tra sự cố máy chủ, lỗi hết thời gian chờ hoặc lỗi Cổng 502/503. 		Có
EXECUTION_BAILOUT_INVALID_RESPONSE Phản hồi JSON không đúng định dạng nên quá trình xử lý đã bị huỷ.

Sử dụng trình xác thực JSON để đảm bảo phản hồi của bạn tuân thủ nghiêm ngặt lược đồ Ý định. 		Có
EXECUTION_GAL_BAD_3P_RESPONSE Không liên kết được tài khoản do định dạng không hợp lệ trong phản hồi mã thông báo.

Xác minh rằng định dạng phản hồi của máy chủ OAuth khớp với yêu cầu của Google. 		Có
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES Tài khoản của người dùng thiếu các quyền cần thiết để thực hiện hành động này.

Kiểm tra các phạm vi được yêu cầu trong quá trình OAuth và đảm bảo các phạm vi đó khớp với các đặc điểm bắt buộc. 		Có
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P Đám mây của đối tác cho biết người dùng đã huỷ liên kết tài khoản của họ.

Đảm bảo mối liên kết agentUserId của bạn ổn định và chưa bị xoá. 		Có
EXECUTION_GAL_NOT_FOUND Mã truy cập và mã làm mới của người dùng được lưu trữ trong Google không hợp lệ hoặc không thể làm mới, khiến người dùng không thể xác thực và truy cập vào dịch vụ của đối tác.

Đảm bảo mã thông báo vẫn hợp lệ và được đồng bộ hoá, xử lý các thay đổi về trạng thái tài khoản một cách thích hợp và yêu cầu người dùng liên kết lại tài khoản nếu mã thông báo được xác nhận là đã bị thu hồi.
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P Tính năng tích hợp đang ở trạng thái chỉ có thể đọc ở phía đối tác.

Kiểm tra xem tài khoản của người dùng có bị tạm ngưng hoặc đang ở chế độ bảo trì "chỉ có thể xem" hay không. 		Có
EXECUTION_GAL_UNLINKED_BY_3P Dịch vụ bên thứ ba đã chủ động huỷ liên kết tài khoản.

Điều tra lý do người dùng bị ngắt kết nối (ví dụ: đặt lại bảo mật). Đảm bảo máy chủ OAuth của đối tác phản hồi chính xác các yêu cầu refresh_token của Google để cấp mã truy cập mới một cách liền mạch. 		Có
EXECUTION_INVALID_JSON Google không phân tích cú pháp được tải trọng phản hồi JSON.

Kiểm tra lỗi cú pháp, thiếu dấu ngoặc hoặc ký tự không hợp lệ trong phản hồi của bạn. 		Có
INVALID_AUTH_TOKEN Google đã nhận được mã lỗi HTTP 401 từ dịch vụ của bạn.

Mã truy cập chưa hết hạn nhưng dịch vụ của bạn đã vô hiệu hoá mã đó. Sử dụng requestId trong Google Cloud Logging để kiểm tra nhật ký dịch vụ nhà thông minh của bạn.
INVALID_JSON Cấu trúc phản hồi không hợp lệ (ví dụ: thiếu các trường bắt buộc).

Xác thực phản hồi của bạn dựa trên Giản đồ JSON ý định. 		Có
MALFORMED_JSON Cấu trúc JSON bị hỏng (ví dụ: chuỗi hoặc đối tượng chưa đóng).

Đảm bảo phương thức thực hiện của bạn sử dụng thư viện JSON chuẩn để chuyển đổi tuần tự phản hồi. 		Có
NOT_IMPLEMENTED Đối tác chưa triển khai ý định hoặc đặc điểm được yêu cầu.

Chỉ đưa vào phản hồi SYNC những đặc điểm mà bạn đã triển khai đầy đủ. 		Có
OPEN_AUTH_FAILURE Mã truy cập của người dùng đã hết hạn và Google không thể làm mới mã đó, hoặc Google đã nhận được mã lỗi HTTP 401 từ dịch vụ của bạn.

Nếu bạn thấy tỷ lệ mã này tăng lên, hãy kiểm tra xem bạn có thấy tỷ lệ lỗi liên quan đến ý định nhà thông minh hoặc yêu cầu mã làm mới tăng lên hay không.
PARTNER_RESPONSE_INVALID_ERROR_CODE Chuỗi errorCode được trả về không nằm trong danh sách được hỗ trợ của Google.

Ánh xạ lỗi nội bộ của bạn với Danh sách lỗi chính thức. 		Có
PARTNER_RESPONSE_INVALID_PAYLOAD Trường payload trong phản hồi không phải là một đối tượng JSON hợp lệ.

Xác minh cấu trúc gốc của phản hồi thực hiện. 		Có
PARTNER_RESPONSE_INVALID_STATUS Phản hồi status không phải là SUCCESS, ERROR hoặc OFFLINE.

Đảm bảo mọi kết quả của thiết bị trong phản hồi của bạn đều có một chuỗi trạng thái hợp lệ. 		Có
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES Câu trả lời không bao gồm kết quả cho tất cả các lệnh/thiết bị được yêu cầu.

Xác thực cấu trúc phản hồi của bạn theo tài liệu dành cho nhà phát triển Google Home. Đảm bảo phản hồi không bị cắt bớt hoặc trả về nội dung trống do lỗi phía máy chủ nội bộ. Mỗi mục trong mảng commands của yêu cầu phải có một mục phản hồi tương ứng. 		Có
PARTNER_RESPONSE_MISSING_DEVICE Một thiết bị cụ thể mà Google yêu cầu đã bị bỏ qua trong phản hồi.

Đảm bảo phản hồi của bạn bao gồm mọi ID được cung cấp trong phần tải trọng yêu cầu. 		Có
PARTNER_RESPONSE_MISSING_PAYLOAD Phản hồi thiếu trường payload bắt buộc.

Đảm bảo đối tượng JSON cấp cao nhất của bạn có chứa khoá payload. 		Có
PARTNER_RESPONSE_NOT_OBJECT Không thể phân tích cú pháp toàn bộ phản hồi dưới dạng đối tượng JSON.

Kiểm tra các ký tự ở cuối hoặc nội dung không phải JSON trong nội dung phản hồi HTTP của bạn. Đảm bảo payload.commands[] là một đối tượng JSON thích hợp có mã nhận dạng, trạng thái và các trạng thái không bắt buộc. 		Có
REQUEST_ID_NOT_FOUND Google không tìm thấy mã theo dõi nội bộ cho yêu cầu này.

Thường là lỗi nền tảng nội bộ; theo dõi các mức tăng đột biến và liên hệ với nhóm hỗ trợ. 		Có
RESOURCE_UNAVAILABLE Tài nguyên được yêu cầu (thiết bị hoặc đặc điểm) không có sẵn.

Kiểm tra xem thiết bị có đang "Bận" hoặc tạm thời bị vô hiệu hoá hay không. 		Có
RESPONSE_TIMEOUT Dịch vụ thực hiện đơn hàng không phản hồi trong vòng 9 giây.

Tối ưu hoá độ trễ của phần phụ trợ; kiểm tra các truy vấn cơ sở dữ liệu chậm hoặc độ trễ mạng theo khu vực. 		Có
RESPONSE_UNAVAILABLE Không nhận được phản hồi từ URL thực hiện đơn hàng của đối tác.

Xác minh rằng dịch vụ của bạn đang chạy và điểm cuối không gặp sự cố. 		Có
TIMEOUT Đã xảy ra lỗi hết thời gian chờ chung trong khi xử lý ý định.

Kiểm tra nhật ký để xem thời gian chờ của dịch vụ nội bộ giữa đám mây và trung tâm thiết bị của bạn. 		Có

Nhật ký Tìm kiếm

Sau khi bạn đã quen với việc giám sát các hoạt động tích hợp bằng chỉ số, bước tiếp theo là khắc phục sự cố các lỗi cụ thể bằng Cloud Logging. Nhật ký lỗi là một mục nhập giống như JSON, có các trường chứa thông tin hữu ích như thời gian, mã lỗi và thông tin chi tiết về ý định nhà thông minh ban đầu.

Có nhiều hệ thống trong Google Cloud gửi nhật ký đến dự án của bạn mọi lúc. Bạn cần viết truy vấn để lọc nhật ký và tìm nhật ký bạn cần. Bạn có thể dựa vào Phạm vi thời gian, Tài nguyên, Mức độ nghiêm trọng của nhật ký hoặc các mục tuỳ chỉnh để tạo truy vấn.

Truy vấn nhật ký trên đám mây

Bạn có thể sử dụng các nút truy vấn để tạo bộ lọc tuỳ chỉnh.

Tạo truy vấn nhật ký trên Cloud Logging

Để chỉ định Phạm vi thời gian, hãy nhấp vào nút chọn phạm vi thời gian rồi chọn một trong các lựa chọn được cung cấp. Thao tác này sẽ lọc nhật ký và hiển thị những nhật ký bắt nguồn từ phạm vi thời gian đã chọn.

Để chỉ định Tài nguyên, hãy nhấp vào trình đơn thả xuống Tài nguyên, sau đó chọn Dự án Hành động trên Trợ lý Google. Thao tác này sẽ thêm một bộ lọc vào truy vấn của bạn để hiển thị nhật ký bắt nguồn từ dự án của bạn.

Sử dụng nút Severity (Mức độ nghiêm trọng) để lọc theo Emergency (Khẩn cấp), Info (Thông tin), Debug (Gỡ lỗi) và các cấp độ nghiêm trọng khác của nhật ký.

Bạn cũng có thể sử dụng trường Truy vấn trong Logs Explorer để nhập các mục tuỳ chỉnh. Công cụ truy vấn mà trường này sử dụng hỗ trợ cả các truy vấn cơ bản như so khớp chuỗi và các loại truy vấn nâng cao hơn, bao gồm bộ so sánh (<, >=, !=) và toán tử boolean (AND, OR, NOT).

Ví dụ: mục tuỳ chỉnh bên dưới sẽ trả về lỗi bắt nguồn từ loại thiết bị LIGHT:

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

Hãy truy cập vào Thư viện truy vấn để xem thêm các ví dụ về cách truy vấn nhật ký một cách hiệu quả.

Kiểm thử bản sửa lỗi

Sau khi xác định được lỗi và áp dụng các bản cập nhật để khắc phục lỗi, bạn nên kiểm tra kỹ các bản sửa lỗi bằng Google Home Test Suite. Chúng tôi cung cấp hướng dẫn sử dụng về cách dùng Test Suite, trong đó hướng dẫn bạn cách kiểm thử các thay đổi một cách hiệu quả.

Tài nguyên học tập

Tài liệu này trình bày các bước khắc phục sự cố trong Hành động nhà thông minh. Bạn cũng có thể xem các lớp học lập trình của chúng tôi để tìm hiểu thêm về cách gỡ lỗi:

Trước
Ghi nhật ký trên đám mây để quan trọng