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

عند إرسال طلب إلى 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.v25.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
    );
    foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() 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 '{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 والتحقيق في مشكلتك.

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