Google Cloud cung cấp cho bạn các công cụ để theo dõi độ tin cậy của các dự án bằng Google Cloud Monitoring và gỡ lỗi các vấn đề bằng Google Cloud Logging nhật ký lỗi. 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ó 2 bước để khắc phục lỗi:
- Theo dõi trạng thái của các dự án bằng các chỉ số nhà thông minh.
- Điều tra các vấn đề bằng cách kiểm tra nội dung mô tả lỗi chi tiết trong nhật ký lỗi.
Bạn có thể kiểm thử Hành động của mình bằng cách chia sẻ với 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.
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 bắt đầu 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 biết một phần hoặc toàn bộ cơ sở người dùng của bạn đang bị gián đoạ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 mức độ hiệu quả 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 biết hệ thống của bạn không thể bắt 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 không mong muố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ố về quá trình tích hợp. Đối với mọi lỗi được nêu bật trong biểu đồ tỷ lệ thành công, một mã lỗi sẽ xuất hiện trong phần phân tích lỗi. Bạn có thể xem các lỗi do 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 nền tảng thường gặp
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 đề do Google Home platform phát hiện. Hãy tham khảo bảng sau để biết thông tin 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ả | Đối tác có thể thực hiện |
|---|---|---|
AGENT_ISSUE |
Đã xảy ra sự cố chung với tác nhân đám mây của đối tác.
Kiểm tra các 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 của đối tác.
Đảm bảo máy chủ của bạn đang trực tuyến, tường lửa không chặn Google và URL chính xác. |
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 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ị đích đang bật nguồn, trực tuyến và được đồ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ủ, thời gian chờ,
hoặc lỗi Cổng 502/503.
|
|
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 để tìm requestId
nhằm tìm ra nguyên nhân gốc.
|
Có |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google đã nhận được lỗi HTTP 4xx (ngoài lỗi 401) từ quá trình thực hiện của bạn.
Kiểm tra nhật ký máy chủ web để tìm các phản hồi 403, 404 hoặc 400. |
Có |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
URL thực hiện bị chặn bởi tệp robots.txt hoặc bộ lọc bảo mật.
Đảm bảo rằng 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 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 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 tính năng 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ủ, thời gian chờ hoặc lỗi Cổng 502/503. |
Có |
EXECUTION_BAILOUT_INVALID_RESPONSE |
Phản hồi JSON bị định dạng sai đến mức quá trình xử lý đã bị huỷ bỏ.
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 thiếu các quyền cần thiết cho hành động này.
Kiểm tra các phạm vi được yêu cầu trong 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 quá trình liên kết agentUserId ổ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, ngăn quá trình 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 xác nhận rằng mã thông báo đã bị thu hồi. |
Có |
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
Quá trình tích hợp đang ở trạng thái chỉ đọc trên 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 ở chế độ bảo trì "chỉ có thể xem" hay không. |
Có |
EXECUTION_GAL_UNLINKED_BY_3P |
Tài khoản đã bị huỷ liên kết chủ động bởi dịch vụ bên thứ ba.
Đ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 thể phân tích cú pháp 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 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ã 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 Lược đồ 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 quá trình thực hiện của bạn sử dụng thư viện JSON tiêu chuẩn để chuyển đổi tuần tự các phản hồi. |
Có |
NOT_IMPLEMENTED |
Ý định hoặc đặc điểm được yêu cầu chưa được đối tác triển khai.
Chỉ đưa các đặc điểm vào phản hồi SYNC 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 có trong danh sách được Google
hỗ trợ.
Liên kết các 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à đối tượng JSON
object 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 |
status phản hồi không phải là SUCCESS, ERROR hoặc OFFLINE.
Đảm bảo mọi kết quả thiết bị trong phản hồi của bạn đều có chuỗi trạng thái hợp lệ. |
Có |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
Phản hồi không chứa 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 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 đề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ể do Google yêu cầu đã bị bỏ qua trong phản hồi.
Đảm bảo phản hồi của bạn chứa mọi ID được cung cấp trong
trọng tải 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 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. Đảm bảo payload.commands[] là đối tượng JSON thích hợp có mã nhận dạng, trạng thái và 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.
Thường là lỗi nền tảng nội bộ; theo dõi các đợt 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ó ở trạng thái "Đ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 không phản hồi trong vòng 9 giây.
Tối ưu hoá độ trễ phần phụ trợ; kiểm tra các truy vấn DB chậm hoặc độ trễ mạng theo khu vực. |
Có |
RESPONSE_UNAVAILABLE |
Không nhận được phản hồi nào từ URL thực hiện 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 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à trung tâm thiết bị. |
Có |
Nhật ký Tìm kiếm
Sau khi bạn đã quen với việc giám sát quá trình tích hợp bằng các 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 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 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ật ký cần thiết. 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.
Bạn có thể sử dụng các nút truy vấn để giúp 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 của Trợ lý Google. Thao tác này sẽ thêm một bộ lọc vào truy vấn để hiển thị 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ý mức độ 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
toán tử 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ề 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 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 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 sử dụng Test Suite, 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 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ề gỡ lỗi nhà thông minh: Hướng dẫn bắt đầu nhanh để gỡ lỗi quá trình tích hợp đám mây nhà thông minh.
- Lớp học lập trình về gỡ lỗi nhà cục bộ: Hướng dẫn bắt đầu nhanh để gỡ lỗi quá trình tích hợp cục bộ nhà thông minh.