معالجة أخطاء واجهة برمجة التطبيقات

عند إرسال طلب إلى Google Ads 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

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 وفحص محتوياتها. استخدِموا التعليمات التالية لتفعيل التسجيل وتسجيل سجلّات واجهة برمجة التطبيقات.

جافا

يُرجى الرجوع إلى دليل تسجيل سجلّات مكتبة برامج 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

لتهيئة التسجيل، أضيفوا السطر التالي في نص Perl البرمجي قبل إجراء أي طلبات بيانات من واجهة برمجة التطبيقات.

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

يُرجى الرجوع إلى دليل تسجيل سجلّات مكتبة Perl للاطّلاع على خيارات إضافية.

curl

يطبع curl الردود غير الناجحة على stderr تلقائيًا.

كيفية معالجة الأخطاء

إذا واجهتم خطأً، إليكم الخطوات التي يجب اتّخاذها:

1. رصد الاستثناء وتسجيل السجلّات: ابدأوا برصد الـ استثناءات وتسجيل سجلّات واجهة برمجة التطبيقات اختياريًا.
2. فحص قائمة errors: اطّلِعوا على كل GoogleAdsError في عنصر GoogleAdsFailure. سيخبركم error_code و message بما حدث
3. التحقّق من قيمة location: يمكن أن يساعدكم ح3}location في تحديد مكان حدوث المشكلة في طلبكم.
4. الرجوع إلى المستندات: بالنسبة إلى رموز الخطأ المحدّدة، اطّلِعوا على صفحة الأخطاء الشائعة أو مرجع رمز الخطأ الكامل لمزيد من التفاصيل حول الخطأ و كيفية حل مشكلة.
5. تعديل طلبكم: استنادًا إلى رسالة الخطأ، صحِّحوا طلب واجهة برمجة التطبيقات. على سبيل المثال، إذا ظهرت لكم الرسالة REQUIRED_FIELD_MISSING، تأكَّدوا من تقديم هذا الحقل في طلبكم.
6. تسجيل request_id: إذا لم تتمكنوا من معرفة كيفية حلّ خطأ ما وكنتم بحاجة إلى التواصل مع فريق الدعم، أدرِجوا سجلّات الطلبات والردود الكاملة للطلب الذي تعذّر إتمامه. تأكَّدوا من تضمين الـ request_id. يساعد هذا المعرّف مهندسي Google في العثور على تفاصيل الطلب الذي تعذّر إتمامه في سجلّات خادم Google Ads API والتحقيق في مشكلتكم.

الخطوات التالية

• راجِعوا الأخطاء الشائعة للاطّلاع على قائمة بـ المشاكل المتكرّرة وحلولها.
• للاطّلاع على المزيد من التقنيات المتقدّمة لمعالجة الأخطاء، بما في ذلك منطق إعادة المحاولة و الفشل الجزئي، يُرجى مراجعة مقالة فهم أخطاء واجهة برمجة التطبيقات.