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 đó trên 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ủa bạn.

Có hai bước để khắc phục lỗi:

  1. Theo dõi trạng thái của các dự án bằng chỉ số 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.

Theo dõi lỗi

Bạn có thể sử dụng Google Cloud Monitoring dashboards để truy cập vào các chỉ số dự án. Có một số biểu đồ chính đặc biệt hữu ích cho việc giám sát 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 giám sát độ tin cậy của các dự án. Sự sụt giảm trong biểu đồ này có thể cho thấy một phần hoặc toàn bộ cơ sở người dùng của bạn bị ngừng hoạt động. Bạn nên theo dõi biểu đồ này một cách chặt chẽ để 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 đồ Phân tích lỗi hữu ích nhất khi bạn cần khắc phục sự cố trên các quy trình 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 phân tích lỗi. Bạn có thể xem các lỗi được Google Home platform gắn cờ và cách khắc phục các lỗi đó trong bảng bên dưới.

Mã lỗi thường gặp trên nền tảng

Sau đâ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à Google Home platform 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à trường hợp ngoại lệ.

Mã lỗi Mô tả Đối tác có thể thực hiện
ACTION_NOT_AVAILABLE Lệnh không hợp lệ đối với trạng thái hiện tại của thiết bị (ví dụ: "Đặt nhiệt độ" khi thiết bị đang Tắt).

Xác minh các đặc điểm của thiết bị và logic trạng thái hiện tại trong quá trình thực hiện. 		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 đang hoạt động, tường lửa không chặn Google và URL chính xác. 		Có
APP_LAUNCH_FAILED Không chạy được ứng dụng bên thứ ba trên thiết bị mục tiêu.

Xác minh appId và đảm bảo rằng ứng dụng được hỗ trợ trên phần cứng mục tiêu. 		Có
AUTH_EXPIRED Mã thông báo truy cập OAuth đã hết hạn và không thể làm mới.

Kiểm tra tính năng xoay mã làm mới và đảm bảo người dùng chưa thu hồi quyền truy cập. 		Có
BACKEND_FAILURE_URL_TIMEOUT Yêu cầu của Google đã hết thời gian chờ khi cố gắng truy cập vào dịch vụ của bạn.

Xác minh rằng dịch vụ của bạn đang trực tuyến, chấp nhận các kết nối và không vượt quá công suất. Ngoài ra, hãy xác minh rằng thiết bị mục tiêu đang bật, có kết nối mạng và đã đồng bộ hoá.
BACKEND_FAILURE_URL_UNREACHABLE Google đã nhận được mã lỗi HTTP 5xx từ dịch vụ của bạn.

Sử dụng requestId trong Google Cloud Logging để kiểm tra nhật ký dịch vụ nhà thông minh. Điều tra các sự cố máy chủ, hết thời gian chờ hoặc lỗi 502/503 Gateway.
CHANNEL_SWITCH_FAILED Thiết bị không chuyển được sang kênh truyền thông được yêu cầu.

Xác minh tên/số kênh và trạng thái đăng ký của người dùng. 		Có
CHARGER_ISSUE Thiết bị báo cáo sự cố phần cứng với hệ thống sạc.

Đối tác nên điều tra thông tin đo từ xa ở cấp phần cứng và tình trạng pin. 		Có
CHECK_PARTNER_APP Lỗi này yêu cầu người dùng mở ứng dụng của đối tác để giải quyết.

Sử dụng mã này cho các lỗi yêu cầu tương tác phức tạp với giao diện người dùng (ví dụ: bản cập nhật chương trình cơ sở). 		Có
COMMAND_FAILED Đã xảy ra lỗi chung trong quá trình thực thi một lệnh.

Kiểm tra nhật ký thực hiện để biết requestId cụ thể nhằm tìm ra nguyên nhân gốc rễ. 		Có
COMMAND_INSERT_FAILED Google không thể xếp hàng hoặc xử lý lệnh cho thiết bị.

Điều tra hiệu suất ghi cơ sở dữ liệu hoặc logic xếp hàng lệnh nội bộ. 		Có
DEVICE_NOT_FOUND Mã thiết bị trong yêu cầu không tồn tại ở phía đối tác.

Đảm bảo rằng phần phụ trợ của bạn luôn đồng bộ hoá Home Graph. Gọi requestSync bất cứ khi nào thiết bị được thêm hoặc xoá. 		Có
ERROR_STATUS Phản hồi cho biết trạng thái "ERROR" (LỖI) không cụ thể mà không có mã.

Luôn thêm một chuỗi errorCode cụ thể để cải thiện TTS của người dùng và dữ liệu trên trang tổng quan. 		Có
EXECUTION_BACKEND_FAILURE_URL_ERROR Google nhận được lỗi HTTP 4xx (ngoài lỗi 401) từ yêu cầu thực hiện của bạn.

Kiểm tra nhật ký máy chủ web để xem có phản hồi 403, 404 hoặc 400 không. 		Có
EXECUTION_BACKEND_FAILURE_URL_ROBOTED URL thực hiện đơn hàng bị chặn bởi tệp robots.txt hoặc bộ lọc bảo mật.

Đảm bảo trình thu thập thông tin/dịch vụ của Google có thể truy cập vào điểm cuối thực hiệ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. Thêm các quy trình kiểm tra tình trạng và xử lý việc thử lại. Điều tra các sự cố máy chủ, hết thời gian chờ hoặc lỗi 502/503 Gateway. 		Có
EXECUTION_BAILOUT_INVALID_RESPONSE Phản hồi JSON có định dạng không đú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 các giản đồ Ý đị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 các yêu cầu của Google. 		Có
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES Tài khoản của người dùng không có 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 rằng các phạm vi đó khớp với những đặc điểm bắt buộc. 		Có
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P Đám mây đố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 việc lập bản đồ agentUserId ổn định và chưa bị xoá. 		Có
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P Chế độ tích hợp ở trạng thái chỉ đọc về 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 hay đang ở chế độ bảo trì "chỉ 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 khiến người dùng bị ngắt kết nối (ví dụ: thiết lập 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 trọng tải phản hồi JSON.

Kiểm tra lỗi cú pháp, dấu ngoặc bị thiếu hoặc ký tự không hợp lệ trong câu trả lời của bạn. 		Có
FAULTY_BATTERY Phần cứng của thiết bị báo cáo rằng pin đang bị lỗi hoặc đã hết.

Hướng dẫn người dùng thay pin thực bằng TTS hoặc Ứng dụng. 		Có
FUNCTION_NOT_SUPPORTED Thiết bị không hỗ trợ chế độ hoặc chức năng được yêu cầu.

Đảm bảo rằng phản hồi SYNC của bạn phản ánh chính xác các chức năng của thiết bị.
HARD_ERROR Lỗi không tạm thời sẽ không giải quyết được nếu không có sự can thiệp thủ công.

Sử dụng mã này cho các lỗi phần cứng vĩnh viễn hoặc trạng thái tài khoản không thể khôi phục. 		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ã này. Sử dụng requestId trong Google Cloud Logging để kiểm tra nhật ký dịch vụ nhà thông minh.
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 về ý định. 		Có
LOCK_FAILURE Khoá thông minh không chuyển sang trạng thái được yêu cầu.

Điều tra tình trạng kẹt cơ học, nguồn điện yếu hoặc lỗi động cơ trên phần cứng khoá. 		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 rằng yêu cầu thực hiện của bạn sử dụng một thư viện JSON tiêu chuẩn để chuyển đổi tuần tự các phản hồi. 		Có
MISSING_STATE Phản hồi QUERY không chứa trạng thái thiết bị được yêu cầu.

Đảm bảo tất cả các đặc điểm được xác định trong SYNC đều được tính đến trong mọi phản hồi QUERY hoặc EXECUTE và trả về tất cả các trạng thái đặc điểm bắt buộc, ngay cả khi không thay đổi. 		Có
NETWORK_PROFILE_NOT_RECOGNIZED Thiết bị không nhận biết được hồ sơ mạng được yêu cầu.

Xác minh rằng chuỗi tên hồ sơ khớp với các hồ sơ được hỗ trợ trong phản hồi SYNC. 		Có
NOT_IMPLEMENTED Đối tác chưa triển khai ý định hoặc đặc điểm được yêu cầu.

Chỉ đưa những đặc điểm mà bạn đã triển khai đầy đủ vào phản hồi SYNC. 		Có
OAUTH_RECONNECT_CALL_TO_ACTION Kích hoạt thông báo để người dùng liên kết lại tài khoản của họ.

Sử dụng mã này khi phiên của người dùng không hợp lệ và yêu cầu người dùng xác thực lại OAuth theo cách thủ công. 		Có
OPEN_AUTH_FAILURE Mã thông báo truy cập của người dùng đã hết hạn và Google không thể làm mới mã thông báo đó 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ần suất xuất hiện mã này tăng lên, hãy kiểm tra xem tần suất xuất hiện các lỗi liên quan đến ý định nhà thông minh hoặc yêu cầu mã làm mới có 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 Google hỗ trợ.

Ánh xạ các lỗi nội bộ của bạn vào 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 đơn hàng. 		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ả về 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 Phản hồ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 dựa trên tài liệu dành cho nhà phát triển Google Home. Đảm bảo rằng phản hồi không bị cắt bớt hoặc trả về nội dung trống do lỗi 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 nhập phản hồi tương ứng. 		Có
PARTNER_RESPONSE_MISSING_DEVICE Một thiết bị cụ thể do Google yêu cầu đã bị bỏ qua trong phản hồi.

Đảm bảo rằng phản hồi của bạn bao gồm mọi ID được cung cấp trong 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 một 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 một đố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. Đả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ó
PROTOCOL_ERROR Đã xảy ra lỗi trong giao thức giao tiếp cơ bản.

Điều tra các vấn đề về tiêu đề HTTP hoặc lỗi bắt tay SSL/TLS. 		Có
RELINK_REQUIRED Người dùng phải liên kết lại tài khoản của họ để tiếp tục sử dụng tính năng tích hợp.

Đảm bảo máy chủ của bạn trả về mã này khi mã làm mới không hợp lệ vĩnh viễn. 		Có
REQUEST_ID_NOT_FOUND Google không tìm thấy mã theo dõi nội bộ cho yêu cầu.

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

Kiểm tra xem thiết bị có đang "Bận" hay đã bị vô hiệu hoá tạm thời 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ễ 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 bị lỗi. 		Có
SCENE_CANNOT_BE_APPLIED Không thể kích hoạt cảnh được yêu cầu (ví dụ: thiếu thiết bị).

Kiểm tra tình trạng bên trong của các cảnh của người dùng trên đám mây đối tác. 		Có
STREAM_UNPLAYABLE Không khởi động được luồng camera hoặc luồng camera đã gặp lỗi.

Xác minh tín hiệu WebRTC/HLS và đảm bảo URL luồng phát hợp lệ. 		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ý để biết thời gian chờ dịch vụ nội bộ giữa đám mây và các trung tâm thiết bị của bạn. 		Có
TRANSIENT_ERROR Lỗi tạm thời là lỗi sẽ tự khắc phục.

Thông thường nhất, những lỗi này biểu hiện dưới dạng kết nối với một thiết bị hoặc dịch vụ bị ngắt. Ngoài ra, nếu không thể mở các kết nối mới đến một máy chủ.
UNABLE_TO_LOCATE_DEVICE Không tìm thấy thiết bị bằng đặc điểm Locator (ví dụ: ping không thành công).

Kiểm tra khả năng kết nối cục bộ của thiết bị (Wi-Fi/Bluetooth). 		Có
UNABLE_TO_RING_DEVICE Đã kết nối được với thiết bị nhưng không kích hoạt được chức năng đổ chuông/cảnh báo của thiết bị.

Xác minh trạng thái cảnh báo/loa và mức âm lượng của phần cứng. 		Có
UNABLE_TO_SILENCE_DEVICE Thiết bị không thể ngừng phát thông báo/chuông đang hoạt động.

Điều tra các lỗi giao tiếp giữa đám mây và thiết bị thực. 		Có
UNEXPECTED_ERROR_CHECK_DEVICE_APP Đã xảy ra lỗi không lường trước được; người dùng nên kiểm tra ứng dụng đối tác.

Sử dụng làm lỗi chung cho những lỗi không có lỗi tương đương cụ thể do Google hỗ trợ. 		Có
UNKNOWN_ERROR Lỗi chung mà không có thêm thông tin chi tiết.

Thêm tính năng ánh xạ lỗi, kiểm tra phòng vệ và ghi nhật ký thích hợp để các lỗi đã biết trả về mã lỗi cụ thể thay vì mã lỗi chung. 		Có
UNLOCK_FAILURE Khoá thông minh không thể chuyển sang trạng thái "Đã mở khoá".

Điều tra các trường hợp kẹt phần cứng, pin yếu hoặc nhập mã PIN không hợp lệ. 		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 các lỗi cụ thể bằng cách sử dụ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 liên quan đến ý định nhà thông minh ban đầu.

Có nhiều hệ thống trong Google Cloud luôn gửi nhật ký đến dự án của bạn. Bạn cần viết các truy vấn để lọc nhật ký và tìm những 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 nhập tuỳ chỉnh để đưa ra 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 đám mây

Để 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à cho thấy những nhật ký bắt nguồn từ phạm vi thời gian đã chọn.

Để chỉ định một 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 của 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 những nhật ký bắt nguồn từ dự án của bạn.

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

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 cả bộ so sánh (<, >=, !=) và toán tử boolean (AND, OR, NOT).

Ví dụ: mục nhập tuỳ chỉnh bên dưới sẽ trả về các 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 để tìm thêm 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 nội dung cập nhật để khắc phục, bạn nên kiểm thử kỹ lưỡng 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 cung cấp các bước khắc phục lỗi trong Thao tác 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ề việc gỡ lỗi:

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