จัดการข้อผิดพลาดของ 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.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"
    }
  ]
}

โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดของ 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
    );
    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};
  }
}

วิธีจับภาพบันทึก

หากต้องการแก้ปัญหาข้อผิดพลาด ให้บันทึกบันทึกข้อผิดพลาดที่เซิร์ฟเวอร์ 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 และตรวจสอบปัญหาของคุณได้

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