عند إرسال طلب إلى 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.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"
}
]
}
يمكنك الرجوع إلى الدليل لمعرفة المزيد عن أخطاء واجهة برمجة التطبيقات.
أمثلة على مكتبات العملاء
يوضّح القسم التالي كيفية التعامل مع الأخطاء في مكتبات البرامج المختلفة من جهة العميل.
Java
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
يُرجى الرجوع إلى دليل تسجيل مكتبة برامج 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 تلقائيًا.
كيفية التعامل مع الأخطاء
في حال ظهور خطأ، إليك الخطوات التي يجب اتّخاذها:
- التقاط الاستثناءات وتسجيلها: ابدأ بالتقاط الاستثناءات وتسجيل سجلات واجهة برمجة التطبيقات اختياريًا.
- فحص قائمة
errors: اطّلِع على كلGoogleAdsErrorفي عنصرGoogleAdsFailure. سيخبرك الرمزerror_codeوالرمزmessageبالمشكلة. - التحقّق من قيمة
location: يمكن أن يساعدك الحقلlocationفي تحديد موضع حدوث المشكلة في طلبك. - الرجوع إلى المستندات: بالنسبة إلى رموز الأخطاء المحدّدة، يمكنك الاطّلاع على صفحة الأخطاء الشائعة أو مرجع رموز الأخطاء الكامل للحصول على مزيد من التفاصيل حول الخطأ وكيفية إصلاحه.
- تعديل طلبك: استنادًا إلى رسالة الخطأ، صحِّح طلب البيانات من واجهة برمجة التطبيقات. على سبيل المثال، إذا رأيت
REQUIRED_FIELD_MISSING، احرص على توفير هذا الحقل في طلبك. - تسجيل
request_id: إذا لم تتمكّن من معرفة كيفية حلّ خطأ وكنت بحاجة إلى التواصل مع فريق الدعم)، يُرجى تضمين سجلات الطلبات والردود الكاملة للطلب الذي تعذّر تنفيذه. احرص على تضمينrequest_id. يساعد هذا المعرّف مهندسي Google في تحديد تفاصيل الطلب الذي تعذّر تنفيذه في سجلات خادم Google Ads API والتحقيق في مشكلتك.
الخطوات التالية
- راجِع الأخطاء الشائعة للاطّلاع على قائمة بالمشاكل المتكررة وحلولها.
- للحصول على المزيد من تقنيات معالجة الأخطاء المتقدّمة، بما في ذلك منطق إعادة المحاولة والفشل الجزئي، يُرجى الاطّلاع على التعرّف على أخطاء واجهة برمجة التطبيقات.