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

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

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

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

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 The error_code และ message จะบอกคุณถึงสิ่งที่ผิด พลาด
  3. ตรวจสอบค่า location: ฟิลด์ location จะช่วยคุณระบุตำแหน่งที่เกิดปัญหาในคำขอ
  4. ดูเอกสารประกอบ: สำหรับรหัสข้อผิดพลาดที่เฉพาะเจาะจง ให้ดูที่หน้าแสดงข้อผิดพลาด ที่พบได้ทั่วไปหรือข้อมูลอ้างอิงรหัสข้อผิดพลาด ฉบับเต็มเพื่อดูรายละเอียดเพิ่มเติมเกี่ยวกับข้อผิดพลาดและ วิธีแก้ไข
  5. ปรับคำขอ: แก้ไขคำขอ API ตามข้อความแสดงข้อผิดพลาด เช่น หากเห็น REQUIRED_FIELD_MISSING ให้ตรวจสอบว่าคุณได้ระบุฟิลด์ดังกล่าวในคำขอแล้ว
  6. บันทึก request_id: หากคุณไม่สามารถหาวิธีแก้ไข ข้อผิดพลาดและต้องติดต่อทีมสนับสนุน ให้ใส่ บันทึกข้อมูลคำขอและการตอบกลับฉบับเต็มสำหรับคำขอที่ล้มเหลว และอย่าลืมใส่ request_id รหัสนี้จะช่วยให้วิศวกรของ Google ค้นหารายละเอียดคำขอที่ล้มเหลวในบันทึกข้อมูลเซิร์ฟเวอร์ Google Ads API และตรวจสอบปัญหาของคุณได้

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