Xử lý lỗi API

Khi bạn gửi yêu cầu đến Google Ads API, yêu cầu đó có thể không thành công vì nhiều lý do. Ví dụ: bạn có thể cung cấp một đối số không hợp lệ hoặc tài khoản của bạn có thể đã đạt đến hạn mức tạo chiến dịch mới. Trong những trường hợp như vậy, API sẽ trả về một lỗi để cho bạn biết vấn đề đã xảy ra.

Hướng dẫn này giải thích cách đọc và xử lý lỗi API để bạn có thể xây dựng các ứng dụng mạnh mẽ hơn.

Cấu trúc lỗi

Nếu bạn đang sử dụng một trong các thư viện ứng dụng của chúng tôi, thì lỗi API sẽ xuất hiện dưới dạng trường hợp ngoại lệ. Các trường hợp ngoại lệ này chứa thông tin chi tiết giúp bạn hiểu lý do xảy ra lỗi.

Google Ads API trả về thông tin lỗi ở định dạng tiêu chuẩn. Nếu xảy ra lỗi, phản hồi sẽ chứa một GoogleAdsFailure đối tượng. Đối tượng này chứa danh sách các đối tượng GoogleAdsError riêng lẻ, mỗi đối tượng nêu chi tiết một lỗi cụ thể.

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

  • error_code: Một mã lỗi cụ thể cho bạn biết loại lỗi, chẳng hạn như AuthenticationError.NOT_ADS_USER.
  • message: Nội dung mô tả mà con người có thể đọc được về lý do xảy ra lỗi.
  • trigger: Giá trị gây ra lỗi, chẳng hạn như "1234".
  • location: Thông tin chi tiết về phần nào trong yêu cầu gây ra lỗi, chẳng hạn như tên trường cụ thể.

Ngoài danh sách lỗi, GoogleAdsFailure còn chứa requestId, là mã nhận dạng duy nhất cho yêu cầu API dẫn đến lỗi.

Ví dụ về lỗi

Sau đây là ví dụ về lỗi ở định dạng JSON. Lỗi này cho biết rằng trường name của ad_group ở chỉ mục 0 bị thiếu trong yêu cầu.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v26.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "requestError": "REQUIRED_FIELD_MISSING"
          },
          "message": "Required field is missing",
          "location": {
            "fieldPathElements": [
              {
                "fieldName": "ad_group",
                "index": 0
              },
              {
                "fieldName": "name"
              }
            ]
          }
        }
      ],
      "requestId": "unique_request_id_12345"
    }
  ]
}

Hãy xem bài viết Tìm hiểu về lỗi API để tìm hiểu thêm về lỗi API.

Ví dụ về thư viện ứng dụng

Phần sau đây cho biết cách xử lý lỗi trong nhiều thư viện ứng dụng.

Java

try {
  // Make an API call.
  ...
} catch (GoogleAdsException gae) {
  // GoogleAdsException is the base class for most exceptions thrown by an
  // API request. Instances of this exception have a message and a
  // GoogleAdsFailure that contains a collection of GoogleAdsErrors that
  // indicate the underlying causes of the GoogleAdsException.
  System.err.printf(
      "Request ID %s failed due to GoogleAdsException. Underlying"
          + " errors:%n",
      gae.getRequestId());
  int i = 0;
  for (GoogleAdsError googleAdsError :
      gae.getGoogleAdsFailure().getErrorsList()) {
    System.err.printf("  Error %d: %s%n", i++, googleAdsError);
  }
}

C#

try
{
    // Make an API call.
    ...
}
catch (GoogleAdsException e)
{
    Console.WriteLine($"Request with ID '{e.RequestId}' has failed.");
    Console.WriteLine("Google Ads failure details:");

    foreach (GoogleAdsError error in e.Failure.Errors)
    {
        Console.WriteLine($"{error.ErrorCode}: {error.Message}");
    }
}

PHP

try {
    // Make an API call.
    ...
} catch (GoogleAdsException $googleAdsException) {
    printf(
        "Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
        $googleAdsException->getRequestId(),
        PHP_EOL,
        PHP_EOL
    );
    $errors = $googleAdsException->getGoogleAdsFailure()->getErrors();
    foreach ($errors as $error) {
        /** @var GoogleAdsError $error */
        printf(
            "\t%s: %s%s",
            $error->getErrorCode()->getErrorCode(),
            $error->getMessage(),
            PHP_EOL
        );
    }
}

Python

try:
    # Make an API call.
    ...
except GoogleAdsException as ex:
    print(
        f"Request with ID '{ex.request_id}' failed with status "
        f"'{ex.error.code().name}' and includes the following errors:"
    )
    for error in ex.failure.errors:
        print(
            f"\tError with message '{error.message}' and code "
            f"'{error.error_code}'."
        )

Ruby

begin
  # Make an API call.
  ...
rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
  puts "API call failed with request ID: #{e.request_id}"
  e.failure.errors.each do |error|
    puts "\t#{error.error_code}: #{error.message}"
  end
end

Perl

# Try sending a mutate request to add the ad group ad.
...
if ($response->isa("Google::Ads::GoogleAds::GoogleAdsException")) {
  printf "Google Ads failure details:\n";
  foreach my $error (@{$response->get_google_ads_failure()->{errors}}) {
    printf "\t%s: %s\n",
      [keys %{$error->{errorCode}}]->[0], $error->{message};
  }
}

Cách thu thập nhật ký

Để khắc phục sự cố, hãy thu thập nhật ký lỗi do máy chủ Google Ads API trả về và kiểm tra nội dung của nhật ký đó. Hãy làm theo hướng dẫn sau để bật tính năng ghi nhật ký và thu thập nhật ký API.

Java

Hãy tham khảo hướng dẫn ghi nhật ký của thư viện ứng dụng Java guide để biết hướng dẫn.

C#

Bạn có thể khởi động tính năng ghi nhật ký bằng cách thêm dòng sau vào phương thức Main trước khi thực hiện bất kỳ lệnh gọi API nào. Điều này đảm bảo rằng thư viện sẽ tạo nhật ký cho tất cả các lệnh gọi API do ứng dụng của bạn thực hiện.

using Google.Ads.GoogleAds.Util;
...

// Detailed logs.
TraceUtilities.Configure(TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE,
    "/path/to/your/logs/details.log", System.Diagnostics.SourceLevels.All);

// Summary logs.
TraceUtilities.Configure(TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
    "/path/to/your/logs/summary.log", System.Diagnostics.SourceLevels.All);

Hãy tham khảo hướng dẫn ghi nhật ký của thư viện.NET để biết các lựa chọn khác.

PHP

Bạn có thể đặt cấu hình ghi nhật ký trong tệp google_ads_php.ini của thư viện ứng dụng. Đặt logLevel thành NOTICE để bắt đầu thu thập nhật ký lỗi chi tiết.

[LOGGING]
; Optional logging settings.
logFilePath = "path/to/your/file.log"
logLevel = "NOTICE"

Hãy tham khảo hướng dẫn ghi nhật ký của thư viện ứng dụng PHP để biết hướng dẫn.

Python

Bạn có thể đặt cấu hình ghi nhật ký trong tệp google-ads.yaml của thư viện ứng dụng. Đặt cấp độ ghi nhật ký thành DEBUG để bắt đầu thu thập nhật ký lỗi chi tiết.

Hãy tham khảo hướng tạo ghi nhật ký của thư viện Python để biết các lựa chọn khác.

Ruby

Bạn có thể đặt cấu hình ghi nhật ký trong tệp google_ads_config.rb của thư viện ứng dụng. Đặt cấp độ ghi nhật ký thành INFO để bắt đầu thu thập nhật ký lỗi chi tiết.

Hãy tham khảo hướng dẫn ghi nhật ký của thư viện Ruby để biết các lựa chọn khác.

Perl

Để khởi chạy tính năng ghi nhật ký, hãy thêm dòng sau vào tập lệnh Perl trước khi thực hiện bất kỳ lệnh gọi API nào.

Google::Ads::GoogleAds::Logging::GoogleAdsLogger::enable_all_logging();

Hãy tham khảo hướng dẫn ghi nhật ký của thư viện Perl để biết các lựa chọn khác.

curl

curl in các phản hồi không thành công vào stderr theo mặc định.

Cách xử lý lỗi

Nếu bạn gặp lỗi, hãy làm theo các bước sau:

  1. Bắt trường hợp ngoại lệ và thu thập nhật ký: Bắt đầu bằng cách bắt các trường hợp ngoại lệ và tuỳ ý thu thập nhật ký API.
  2. Kiểm tra danh sách errors: Xem từng GoogleAdsError trong đối tượng GoogleAdsFailure. The error_code và message sẽ cho bạn biết vấn đề đã xảy ra.
  3. Kiểm tra giá trị location: Trường location có thể giúp bạn xác định vị trí xảy ra vấn đề trong yêu cầu của mình.
  4. Tham khảo tài liệu: Đối với các mã lỗi cụ thể, hãy xem trang các lỗi thường gặp hoặc tài liệu tham khảo đầy đủ về mã lỗi để biết thêm thông tin chi tiết về lỗi và cách khắc phục.
  5. Điều chỉnh yêu cầu: Dựa trên thông báo lỗi, hãy sửa yêu cầu API của bạn. Ví dụ: nếu bạn thấy REQUIRED_FIELD_MISSING, hãy đảm bảo rằng bạn cung cấp trường đó trong yêu cầu của mình.
  6. Ghi nhật ký request_id: Nếu bạn không thể tìm ra cách giải quyết lỗi và cần liên hệ với nhóm hỗ trợ, hãy cung cấp nhật ký đầy đủ về yêu cầu và phản hồi cho yêu cầu không thành công. Đảm bảo cung cấp request_id. Mã nhận dạng này giúp các kỹ sư của Google xác định vị trí thông tin chi tiết về yêu cầu không thành công trong nhật ký máy chủ Google Ads API và điều tra vấn đề của bạn.

Các bước tiếp theo

  • Xem bài viết Các lỗi thường gặp để biết danh sách các vấn đề thường gặp và giải pháp cho các vấn đề đó.
  • Để biết các kỹ thuật xử lý lỗi nâng cao hơn, bao gồm cả logic thử lại và lỗi một phần, hãy xem bài viết Tìm hiểu về lỗi API errors.