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

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

جاوا

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

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

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

  1. استثنا را دریافت کنید و گزارش‌ها را ضبط کنید: با دریافت استثناها و به‌صورت اختیاری ضبط گزارش‌های میانای برنامه‌سازی کاربردی شروع کنید.
  2. بررسی فهرست errors: به هر GoogleAdsError در GoogleAdsFailure شیء نگاه کنید. error_code و message به شما می‌گویند چه مشکلی پیش آمده است.
  3. مقدار location را بررسی کنید: فیلد location می‌تواند به شما کمک کند دقیقاً مشخص کنید مشکل در کجای درخواست شما رخ داده است.
  4. مراجعه به اسناد: برای کدهای خطای خاص، صفحه خطاهای رایج یا مرجع کامل کدهای خطا را بررسی کنید تا جزئیات بیشتری درباره خطا و نحوه رفع آن به‌دست آورید.
  5. درخواستتان را اصلاح کنید: براساس پیام خطا، درخواست «میانای برنامه‌سازی کاربردی» خود را اصلاح کنید. برای مثال، اگر REQUIRED_FIELD_MISSING را می‌بینید، مطمئن شوید که آن فیلد را در درخواستتان ارائه دهید.
  6. گزارش request_id: اگر نمی‌توانید نحوه رفع خطا را پیدا کنید و نیاز به تماس با پشتیبانی دارید، گزارش‌های کامل درخواست و پاسخ را برای درخواست ناموفق ارائه دهید. حتماً request_id را اضافه کنید. این شناسه به مهندسان Google کمک می‌کند جزئیات درخواست ناموفق را در گزارش‌های سرور Google Ads API پیدا کنند و مشکلتان را بررسی کنند.

مراحل بعدی

قبلی
راه‌اندازی سریع
بعدی
خطاهای رایج