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:
- Theo dõi trạng thái của dự án bằng các chỉ số về nhà thông minh.
- Đ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.
Bạn có thể tuỳ ý thử nghiệm Hành động của mình bằng cách chia sẻ Hành động đó với những người dùng khác. Hãy nhớ xử lý lỗi và ngoại lệ một cách thích hợp.
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 đồ Độ trễ phân vị thứ 95 là một chỉ báo quan trọng cho biết hiệu suất của quá trình tích hợp Cloud-to-cloud đối với người dùng. Sự biến động đột ngột trong biểu đồ này có thể cho thấy hệ thống của bạn không thể theo kịp các yêu cầu. Bạn nên kiểm tra biểu đồ này định kỳ để phát hiện mọi hành vi bất thường.
- 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 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à 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à 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.
Bạn có thể sử dụng các nút truy vấn để tạo bộ lọc tuỳ chỉnh.
Để 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:
- Lớp học lập trình về cách gỡ lỗi nhà thông minh: Hướng dẫn bắt đầu nhanh về cách gỡ lỗi tích hợp đám mây cho nhà thông minh.
- Lớp học lập trình về cách gỡ lỗi cho Local Home: Hướng dẫn bắt đầu nhanh về cách gỡ lỗi cho tính năng tích hợp cục bộ của nhà thông minh.