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 giới hạn về số lượng chiến dịch mới mà bạn có thể tạo. 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ể tạo 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 các 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 chuẩn. Nếu xảy ra lỗi, phản hồi sẽ chứa một đối tượng GoogleAdsFailure. Đối tượng này chứa một 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 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 của 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. Đây là giá trị 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 yêu cầu thiếu trường name của ad_group tại chỉ mục 0.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v22.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 tham khảo hướng dẫn của chúng tôi để 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
    );
    foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() 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 '{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 ghi nhật ký

Để khắc phục lỗi, hãy ghi lại 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à ghi lại nhật ký API.

Java

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

C#

Bạn có thể khởi tạo 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 tất cả thư viện đều 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ý thư viện.NET để biết thêm các lựa chọn.

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 ghi lại 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ý 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 ghi lại nhật ký lỗi chi tiết.

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

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 ghi lại nhật ký lỗi chi tiết.

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

Perl

Để khởi tạo 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ý thư viện Perl để biết thêm các lựa chọn.

curl

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

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 ngoại lệ và ghi nhật ký: Bắt đầu bằng cách bắt các ngoại lệ và tuỳ ý ghi nhật ký API.
  2. Kiểm tra danh sách errors: Xem xét từng GoogleAdsError trong đối tượng GoogleAdsFailure. 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 chính xác vị trí xảy ra vấn đề trong yêu cầu của bạn.
  4. Tham khảo tài liệu: Đối với một số mã lỗi cụ thể, hãy kiểm tra trang 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 về lỗi và cách khắc phục.
  5. Điều chỉnh yêu cầu của bạn: Dựa trên thông báo lỗi, hãy điều chỉnh 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. Đừng quên thêm 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 trên 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

  • Hãy xem phần 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 khắc phục.
  • Để biết thêm các kỹ thuật xử lý lỗi nâng cao, bao gồm cả logic thử lại và lỗi một phần, hãy xem phần Tìm hiểu về lỗi API.