จัดการข้อผิดพลาดของ API

เมื่อส่งคำขอไปยัง Google Ads API คำขออาจล้มเหลวด้วยเหตุผลต่างๆ เช่น คุณอาจระบุอาร์กิวเมนต์ที่ไม่ถูกต้อง หรือบัญชีของคุณ อาจสร้างแคมเปญใหม่ถึงขีดจำกัดแล้ว ในกรณีดังกล่าว API จะแสดงข้อผิดพลาดเพื่อแจ้งให้คุณทราบว่าเกิดอะไรขึ้น

คู่มือนี้อธิบายวิธีอ่านและจัดการข้อผิดพลาดของ API เพื่อให้คุณสร้างแอปพลิเคชันที่แข็งแกร่งยิ่งขึ้นได้

โครงสร้างข้อผิดพลาด

หากคุณใช้ไลบรารีของไคลเอ็นต์ของเรา ข้อผิดพลาดของ API จะปรากฏเป็นข้อยกเว้น ข้อยกเว้นเหล่านี้มีรายละเอียดที่จะช่วยให้คุณ เข้าใจสาเหตุที่เกิดข้อผิดพลาด

Google Ads API จะแสดงข้อมูลข้อผิดพลาดในรูปแบบมาตรฐาน หากเกิดข้อผิดพลาด การตอบกลับจะมีออบเจ็กต์ GoogleAdsFailure ออบเจ็กต์นี้ มีรายการออบเจ็กต์GoogleAdsErrorแต่ละรายการ ซึ่งแต่ละรายการจะแสดงรายละเอียด ข้อผิดพลาดที่เฉพาะเจาะจง

ออบเจ็กต์ GoogleAdsError แต่ละรายการมีข้อมูลต่อไปนี้

  • error_code: รหัสข้อผิดพลาดที่เฉพาะเจาะจงซึ่งจะบอกประเภทข้อผิดพลาด เช่น AuthenticationError.NOT_ADS_USER
  • message: คำอธิบายที่มนุษย์อ่านได้ เกี่ยวกับสาเหตุที่เกิดข้อผิดพลาด
  • trigger: ค่าที่ทำให้เกิดข้อผิดพลาด เช่น "1234"
  • location: รายละเอียดเกี่ยวกับส่วนใดของคำขอที่ทำให้เกิดข้อผิดพลาด เช่น ชื่อฟิลด์ที่เฉพาะเจาะจง

นอกเหนือจากรายการข้อผิดพลาดแล้ว GoogleAdsFailure ยังมี requestId ซึ่งเป็นตัวระบุ ที่ไม่ซ้ำกันสำหรับคำขอ API ที่ทำให้เกิดข้อผิดพลาด

ตัวอย่างข้อผิดพลาด

ตัวอย่างลักษณะข้อผิดพลาดในรูปแบบ JSON มีดังนี้ ข้อผิดพลาดนี้ บ่งชี้ว่าไม่มีฟิลด์ name ของ ad_group ที่ดัชนี 0 ในคำขอ

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v25.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"
    }
  ]
}

ดูข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดของ API ได้ที่ทำความเข้าใจข้อผิดพลาดของ API

ตัวอย่างไลบรารีของไคลเอ็นต์

ส่วนต่อไปนี้แสดงวิธีจัดการข้อผิดพลาดในไคลเอ็นต์ไลบรารีต่างๆ

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};
  }
}

วิธิจับบันทึก

หากต้องการแก้ปัญหาข้อผิดพลาด ให้บันทึกข้อผิดพลาดที่เซิร์ฟเวอร์ Google Ads API แสดง และตรวจสอบเนื้อหา ทำตามวิธีการต่อไปนี้เพื่อเปิดใช้การบันทึกและ บันทึกข้อมูล API

Java

ดูวิธีการได้ในคู่มือการบันทึกของไลบรารีของไคลเอ็นต์ Java

C#

คุณเริ่มต้นการบันทึกได้โดยเพิ่มบรรทัดต่อไปนี้ในMain เมธอดก่อนที่จะเรียก API ซึ่งจะช่วยให้มั่นใจได้ว่าไลบรารี จะสร้างบันทึกสำหรับการเรียก API ทั้งหมดที่แอปพลิเคชันของคุณทำ

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);

ดูตัวเลือกเพิ่มเติมได้ในคู่มือการบันทึกของไลบรารี .NET

PHP

คุณตั้งค่าการบันทึกได้ในไฟล์ google_ads_php.ini ของไลบรารีไคลเอ็นต์ ตั้งค่า logLevel เป็น NOTICE เพื่อเริ่มบันทึกข้อผิดพลาดโดยละเอียด

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

ดูวิธีการได้ในคู่มือการบันทึกของไลบรารีของไคลเอ็นต์ PHP

Python

คุณตั้งค่าการบันทึกได้ในไฟล์ google-ads.yaml ของไลบรารีไคลเอ็นต์ ตั้งค่าระดับการบันทึกเป็น DEBUG เพื่อเริ่มบันทึกข้อผิดพลาดโดยละเอียด

ดูตัวเลือกเพิ่มเติมได้ที่คู่มือการบันทึกของไลบรารี Python

Ruby

คุณตั้งค่าการบันทึกได้ในไฟล์ google_ads_config.rb ของไลบรารีไคลเอ็นต์ ตั้งค่าระดับการบันทึกเป็น INFO เพื่อเริ่มบันทึกข้อผิดพลาดโดยละเอียด

ดูตัวเลือกเพิ่มเติมได้ที่คู่มือการบันทึกของไลบรารี Ruby

Perl

หากต้องการเริ่มต้นการบันทึก ให้เพิ่มบรรทัดต่อไปนี้ในสคริปต์ Perl ก่อน ทำการเรียก API

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

ดูตัวเลือกเพิ่มเติมได้ในคู่มือการบันทึกของไลบรารี Perl

curl

curl จะพิมพ์การตอบกลับที่ไม่สำเร็จไปยัง stderr โดยค่าเริ่มต้น

วิธีจัดการข้อผิดพลาด

หากพบข้อผิดพลาด ให้ทำตามขั้นตอนต่อไปนี้

  1. ดักข้อยกเว้นและบันทึกข้อมูล: เริ่มต้นด้วยการดักข้อยกเว้นและบันทึกข้อมูล API (ไม่บังคับ)
  2. ตรวจสอบerrorsรายการ: ดูแต่ละGoogleAdsErrorในออบเจ็กต์ GoogleAdsFailure error_code และ message จะบอกให้ทราบว่าเกิดข้อผิดพลาด อะไรขึ้น
  3. ตรวจสอบlocationค่า: ฟิลด์ location จะช่วยให้คุณระบุได้ว่าปัญหาเกิดขึ้นที่ใดในคำขอ
  4. อ่านเอกสารประกอบ: สำหรับรหัสข้อผิดพลาดที่เฉพาะเจาะจง ให้ไปที่หน้าข้อผิดพลาด ที่พบบ่อยหรือข้อมูลอ้างอิงรหัสข้อผิดพลาด ฉบับเต็มเพื่อดูรายละเอียดเพิ่มเติมเกี่ยวกับข้อผิดพลาดและ วิธีแก้ไข
  5. ปรับคำขอ: แก้ไขคำขอ API ตามข้อความแสดงข้อผิดพลาด เช่น หากเห็น REQUIRED_FIELD_MISSING โปรดตรวจสอบว่าคุณได้ระบุฟิลด์ดังกล่าวในคำขอ
  6. บันทึกrequest_id: หากคุณไม่ทราบวิธีแก้ไขข้อผิดพลาดและต้องติดต่อทีมสนับสนุน โปรดระบุบันทึกคำขอและการตอบกลับแบบเต็มสำหรับคำขอที่ไม่สำเร็จ อย่าลืมใส่ request_id รหัสนี้จะช่วยให้วิศวกรของ Google ค้นหารายละเอียดคำขอที่ไม่สำเร็จในบันทึกของเซิร์ฟเวอร์ Google Ads API และตรวจสอบปัญหาของคุณ

ขั้นตอนถัดไป