خطاهای API را مدیریت کنید

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

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

ساختار خطا

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

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

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

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

جاوا

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

سی شارپ

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

پی اچ پی

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

پایتون

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}'.")

روبی

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 استفاده کنید.

جاوا

برای دستورالعمل‌ها به راهنمای ثبت وقایع کتابخانه کلاینت جاوا مراجعه کنید.

سی شارپ

شما می‌توانید با اضافه کردن خط زیر در متد Main خود، قبل از انجام هرگونه فراخوانی API، ثبت وقایع (logging) را مقداردهی اولیه کنید. این کار تضمین می‌کند که تمام کتابخانه برای تمام فراخوانی‌های 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 مراجعه کنید.

پی اچ پی

می‌توانید پیکربندی ثبت وقایع (logging) را در فایل google_ads_php.ini کتابخانه کلاینت خود تنظیم کنید. برای شروع ثبت وقایع خطای دقیق، سطح log را روی NOTICE تنظیم کنید.

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

برای دستورالعمل‌ها به راهنمای ثبت وقایع کتابخانه کلاینت PHP مراجعه کنید.

پایتون

می‌توانید پیکربندی ثبت وقایع (logging) را در فایل google-ads.yaml کتابخانه کلاینت خود تنظیم کنید. سطح ثبت وقایع (logging) را روی DEBUG تنظیم کنید تا ثبت وقایع خطای دقیق آغاز شود.

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

روبی

می‌توانید پیکربندی ثبت وقایع را در فایل google_ads_config.rb کتابخانه کلاینت خود تنظیم کنید. برای شروع ثبت وقایع خطای دقیق، سطح ثبت وقایع را روی INFO تنظیم کنید.

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

پرل

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

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

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

حلقه زدن

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 Ads API پیدا کرده و مشکل شما را بررسی کنند.

مراحل بعدی

  • برای فهرستی از مشکلات رایج و راه‌حل‌های آنها ، خطاهای رایج را مرور کنید.
  • برای تکنیک‌های پیشرفته‌تر مدیریت خطا، از جمله منطق تلاش مجدد و شکست جزئی، به بخش «درک خطاهای API» مراجعه کنید.