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

عند إرسال طلب إلى 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: يمكن أن يساعدك حقل location في تحديد مكان حدوث المشكلة في طلبك.
4. الرجوع إلى المستندات: بالنسبة إلى رموز الأخطاء المحدّدة، يمكنك الاطّلاع على صفحة الأخطاء الشائعة أو مرجع رموز الأخطاء الكامل للحصول على مزيد من التفاصيل حول الخطأ وكيفية حل مشكلته.
5. تعديل طلبك: صحِّح طلب البيانات من واجهة برمجة التطبيقات استنادًا إلى رسالة الخطأ. على سبيل المثال، إذا ظهر لك REQUIRED_FIELD_MISSING، تأكَّد من توفير هذا الحقل في طلبك.
6. تسجيل request_id: إذا لم تتمكّن من معرفة كيفية حلّ خطأ ما وكنت بحاجة إلى التواصل مع فريق الدعم، يُرجى تضمين سجلّات الطلبات والردود الكاملة للطلب الذي تعذّر إكماله. يُرجى التأكّد من تضمين request_id. يساعد هذا المعرّف مهندسي Google في تحديد تفاصيل الطلب الذي تعذّر تنفيذه في سجلّات خادم Google Ads API والتحقيق في مشكلتك.

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

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