رسیدگی به خطاهای میانای برنامه‌سازی کاربردی

وقتی درخواستی به Google Ads API ارسال می‌کنید، ممکن است به دلایل مختلفی ناموفق باشد. برای مثال، ممکن است آرگومان نامعتبری ارائه کرده باشید، یا حسابتان به حد مجاز برای ایجاد پویش‌های جدید رسیده باشد. در چنین مواردی، API خطایی برمی‌گرداند تا به شما اطلاع دهد چه مشکلی پیش آمده است.

این راهنما توضیح می‌دهد که چگونه خطاهای API را بخوانید و مدیریت کنید تا بتوانید برنامه‌های قوی‌تری بسازید.

ساختار خطا

اگر از یکی از کتابخانه‌های کارخواه ما استفاده می‌کنید، خطاهای میانای برنامه‌سازی کاربردی به‌عنوان استثنا ظاهر می‌شوند. این استثناها حاوی جزئیاتی هستند که به شما کمک می‌کنند دلیل وقوع خطا را درک کنید.

Google Ads API اطلاعات خطا را در قالب استاندارد برمی‌گرداند. اگر خطایی رخ دهد، پاسخ حاوی شیء GoogleAdsFailure خواهد بود. این شیء حاوی فهرستی از اشیاء GoogleAdsError تکی است که هرکدام جزئیات خطای خاصی را نشان می‌دهد.

هر شیء GoogleAdsError موارد زیر را ارائه می‌دهد:

  • error_code: کد خطای خاصی که نوع خطا را به شما می‌گوید، مثل AuthenticationError.NOT_ADS_USER.
  • message: شرحی قابل‌خواندن برای انسان درباره دلیل وقوع خطا.
  • trigger: مقداری که باعث بروز خطا شده است، مثل «1234».
  • location: جزئیات مربوط به اینکه کدام بخش از درخواست باعث بروز خطا شده است، مثلاً نام فیلدی خاص.

علاوه‌بر فهرست خطاها، GoogleAdsFailure حاوی requestId است که شناسه یکتایی برای درخواست میانای برنامه‌سازی کاربردی است که منجر به خطا شده است.

نمونه خطا

در اینجا مثالی از نحوه نمایش خطا در قالب 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"
    }
  ]
}

برای کسب اطلاعات بیشتر درباره خطاهای میانای برنامه‌سازی کاربردی، به درک خطاهای میانای برنامه‌سازی کاربردی مراجعه کنید.

نمونه‌های کتابخانه کارخواه

بخش زیر نحوه رسیدگی به خطاها را در کتابخانه‌های مختلف مشتری نشان می‌دهد.

جاوا

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

پرل

# 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 مراجعه کنید.

C#‎

می‌توانید با افزودن خط زیر در روش Main قبل‌از برقراری هرگونه تماس با میانای برنامه‌سازی کاربردی، ثبت گزارش را مقداردهی اولیه کنید. این کار تضمین می‌کند که کتابخانه برای همه فراخوانی‌های میانای برنامه‌سازی کاربردی که توسط برنامه شما انجام می‌شود، گزارش تولید می‌کند.

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 خود قبل‌از برقراری هرگونه تماس API اضافه کنید.

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

برای گزینه‌های بیشتر، به راهنمای ثبت گزارش کتابخانه Perl مراجعه کنید.

curl

curl پاسخ‌های ناموفق را به‌طور پیش‌فرض در stderr چاپ می‌کند.

نحوه رسیدگی به خطاها

اگر با خطایی مواجه شدید، مراحل زیر را دنبال کنید:

  1. استثنا را بگیرید و گزارش‌ها را ضبط کنید: با گرفتن استثناها و به‌طور اختیاری ضبط گزارش‌های میانای برنامه‌سازی کاربردی شروع کنید.
  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 پیدا کنند و مشکل شما را بررسی کنند.

مراحل بعدی