Tìm hiểu về lỗi API

Hướng dẫn này giải thích cách API Google Ads xử lý và truyền đạt lỗi. Việc hiểu rõ cấu trúc và ý nghĩa của các lỗi API là rất quan trọng để xây dựng các ứng dụng mạnh mẽ có thể xử lý các vấn đề một cách hiệu quả, từ đầu vào không hợp lệ cho đến tình trạng dịch vụ tạm thời không hoạt động.

Google Ads API tuân theo mô hình lỗi API tiêu chuẩn của Google, dựa trên mã trạng thái gRPC. Mỗi phản hồi API dẫn đến lỗi đều chứa một đối tượng Status chứa:

• Mã lỗi bằng số.
• Một thông báo lỗi.
• Không bắt buộc, thông tin bổ sung về lỗi.

Mã lỗi chuẩn

Google Ads API sử dụng một bộ mã lỗi chuẩn do gRPC và HTTP xác định. Các mã này cung cấp thông tin chung về loại lỗi. Trước tiên, bạn phải luôn kiểm tra mã số này để hiểu rõ bản chất cơ bản của vấn đề.

Bảng sau đây tóm tắt các mã phổ biến nhất mà bạn có thể gặp phải khi sử dụng Google Ads API:

Để biết thêm thông tin chi tiết về các mã này, hãy tham khảo Hướng dẫn thiết kế API – Mã lỗi.

Tìm hiểu thông tin chi tiết về lỗi

Ngoài mã cấp cao nhất, Google Ads API còn cung cấp thông tin lỗi cụ thể hơn trong trường details của đối tượng Status. Trường này thường chứa một giao thức GoogleAdsFailure, trong đó có một danh sách các đối tượng GoogleAdsError riêng lẻ.

Mỗi đối tượng GoogleAdsFailure đều chứa:

• errors: Một danh sách các đối tượng GoogleAdsError, mỗi đối tượng trình bày chi tiết một lỗi cụ thể đã xảy ra.
• request_id: Một mã nhận dạng duy nhất cho yêu cầu, hữu ích cho mục đích gỡ lỗi và hỗ trợ.

Mỗi đối tượng GoogleAdsError đều cung cấp:

• error_code: ErrorCode (các lỗi thường gặp) cụ thể hơn về Google Ads API, chẳng hạn như AuthenticationError.NOT_ADS_USER.
• message: Nội dung mô tả cụ thể về lỗi mà con người có thể đọc được.
• trigger: Value gây ra lỗi (nếu có).
• location: Một ErrorLocation mô tả vị trí xảy ra lỗi trong yêu cầu, bao gồm cả đường dẫn trường.
• details: ErrorDetails bổ sung, chẳng hạn như lý do lỗi chưa được xuất bản.

Ví dụ về thông tin chi tiết về lỗi

Khi bạn nhận được lỗi, thư viện ứng dụng sẽ cho phép bạn truy cập vào những thông tin chi tiết này. Ví dụ: INVALID_ARGUMENT (Mã 3) có thể có thông tin chi tiết GoogleAdsFailure như sau:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v25.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ],
      "requestId": "AbCdEfGhIjKlMnOpQrStUv"
    }
  ]
}

Trong ví dụ này, mặc dù có INVALID_ARGUMENT ở cấp cao nhất, nhưng thông tin chi tiết về GoogleAdsFailure cho biết rằng các trường name và description gây ra vấn đề và lý do (tương ứng là REQUIRED và TOO_SHORT).

Tìm thông tin chi tiết về lỗi

Cách bạn truy cập vào thông tin chi tiết về lỗi phụ thuộc vào việc bạn đang sử dụng các lệnh gọi API tiêu chuẩn, lỗi một phần hay truyền trực tuyến.

Lệnh gọi API chuẩn và lệnh gọi API truyền trực tuyến

Khi một lệnh gọi API không thành công mà không sử dụng lỗi một phần, bao gồm cả lệnh gọi truyền trực tuyến, đối tượng GoogleAdsFailure sẽ được trả về trong siêu dữ liệu theo sau trong tiêu đề phản hồi gRPC. Nếu bạn đang sử dụng REST cho các lệnh gọi tiêu chuẩn, thì GoogleAdsFailure sẽ được trả về trong phản hồi HTTP. Thư viện ứng dụng thường hiển thị điều này dưới dạng một trường hợp ngoại lệ có thuộc tính GoogleAdsFailure.

Không thực hiện được một phần

Nếu bạn đang sử dụng lỗi một phần, thì các lỗi cho những thao tác không thành công sẽ được trả về trong trường partial_failure_error của phản hồi, chứ không phải trong tiêu đề phản hồi. Trong trường hợp này, GoogleAdsFailure được nhúng trong một đối tượng google.rpc.Status trong phản hồi.

Công việc theo lô

Đối với xử lý hàng loạt, bạn có thể tìm thấy lỗi cho từng thao tác bằng cách gọi BatchJobService.ListBatchJobResults sau khi công việc hoàn tất. Mỗi kết quả thao tác sẽ bao gồm một trường status chứa thông tin chi tiết về lỗi nếu thao tác không thành công.

Mã yêu cầu

request-id là một chuỗi duy nhất xác định yêu cầu API của bạn và rất cần thiết cho việc khắc phục sự cố.

Bạn có thể tìm thấy request-id ở nhiều nơi:

• GoogleAdsFailure: Nếu lệnh gọi API không thành công và GoogleAdsFailure được trả về, thì lệnh gọi đó sẽ chứa một request_id.
• Siêu dữ liệu theo sau: Đối với cả yêu cầu thành công và không thành công, request-id đều có trong siêu dữ liệu theo sau của phản hồi gRPC.
• Tiêu đề phản hồi: Đối với cả yêu cầu thành công và không thành công, request-id cũng có trong tiêu đề phản hồi gRPC và phản hồi HTTP, ngoại trừ các yêu cầu truyền trực tuyến thành công.
• SearchGoogleAdsStreamResponse: Đối với các yêu cầu phát trực tuyến, mỗi thông báo SearchGoogleAdsStreamResponse đều chứa một trường request_id.

Khi ghi nhật ký lỗi hoặc liên hệ với nhóm hỗ trợ, hãy nhớ cung cấp request-id để giúp chẩn đoán vấn đề.

Các phương pháp hay nhất để xử lý lỗi

Để tạo các ứng dụng có khả năng phục hồi, hãy triển khai các phương pháp hay nhất sau:

1. Kiểm tra thông tin chi tiết về lỗi: Luôn phân tích cú pháp trường details của đối tượng Status, đặc biệt là tìm GoogleAdsFailure. error_code, message và location thật chi tiết trong GoogleAdsError cung cấp thông tin hữu ích nhất để gỡ lỗi và thu thập ý kiến phản hồi của người dùng.

2. Phân biệt lỗi phía máy khách với lỗi phía máy chủ:

   • Lỗi phía máy khách: Các mã như INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Những lỗi này yêu cầu bạn thay đổi yêu cầu hoặc trạng thái/thông tin đăng nhập của ứng dụng. Đừng thử lại yêu cầu mà không giải quyết vấn đề.
   • Lỗi máy chủ: Các mã như UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Những lỗi này cho thấy dịch vụ API đang gặp vấn đề tạm thời.

3. Triển khai chiến lược thử lại:

   • Thời điểm thử lại: Chỉ thử lại đối với các lỗi máy chủ tạm thời, chẳng hạn như UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN và ABORTED.
   • Thuật toán thời gian đợi luỹ thừa: Sử dụng thuật toán thời gian đợi luỹ thừa để chờ khoảng thời gian tăng dần giữa các lần thử lại. Điều này giúp tránh gây quá tải cho một dịch vụ vốn đã chịu nhiều áp lực. Ví dụ: đợi 1 giây, sau đó đợi 2 giây, rồi đợi 4 giây, tiếp tục cho đến số lần thử lại tối đa hoặc tổng thời gian chờ.
   • Biên độ: Thêm một lượng nhỏ "biên độ" ngẫu nhiên vào độ trễ khi giảm tốc để ngăn chặn vấn đề "đàn gia súc" khi nhiều ứng dụng đồng thời thử lại.

4. Ghi nhật ký kỹ lưỡng: Ghi nhật ký toàn bộ phản hồi lỗi, bao gồm tất cả thông tin chi tiết, đặc biệt là mã yêu cầu. Thông tin này rất cần thiết cho việc gỡ lỗi và báo cáo vấn đề cho Nhóm hỗ trợ Google (nếu cần).

5. Cung cấp ý kiến phản hồi cho người dùng: Dựa trên mã và thông báo cụ thể GoogleAdsError, hãy cung cấp ý kiến phản hồi rõ ràng và hữu ích cho người dùng ứng dụng của bạn. Ví dụ: thay vì chỉ nói "Đã xảy ra lỗi", bạn có thể nói "Bạn phải nhập tên chiến dịch" hoặc "Không tìm thấy mã nhóm quảng cáo được cung cấp".

Bằng cách làm theo các nguyên tắc này, bạn có thể chẩn đoán và xử lý hiệu quả các lỗi do Google Ads API trả về, nhờ đó tạo ra các ứng dụng ổn định và thân thiện với người dùng hơn.