تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

يوضّح هذا الدليل كيف تعالج Google Ads API الأخطاء وتُبلغ عنها. إنّ فهم بنية أخطاء واجهة برمجة التطبيقات ومعناها أمر بالغ الأهمية لإنشاء تطبيقات قوية يمكنها التعامل مع المشاكل بسلاسة، بدءًا من الإدخال غير الصالح إلى عدم توفّر الخدمة مؤقتًا.

تتّبع Google Ads API نموذج الأخطاء العادي في Google API، والذي يستند إلى رموز الحالة في gRPC. يتضمّن كل رد من واجهة برمجة التطبيقات يؤدي إلى حدوث خطأ كائن Status يحتوي على ما يلي:

رمز خطأ رقمي
رسالة خطأ
تفاصيل إضافية اختيارية عن الخطأ

رموز الخطأ المتعلقة بالعناوين الأساسية

تستخدِم Google Ads API مجموعة من رموز الخطأ الأساسية التي يحدّدها gRPC وHTTP. تقدّم هذه الرموز إشارة عالية المستوى إلى نوع الخطأ. يجب دائمًا التحقّق من هذا الرمز الرقمي أولاً لفهم الطبيعة الأساسية للمشكلة.

يلخّص الجدول التالي الرموز الأكثر شيوعًا التي قد تواجهها عند استخدام Google Ads API:

رمز gRPC	رمز HTTP	اسم التعداد	الوصف	الإرشادات
0	200	`OK`	ما مِن خطأ، يشير إلى النجاح.	لا ينطبق
1	499	`CANCELLED`	تم إلغاء العملية، وعادةً ما يتم ذلك من قِبل العميل.	يشير ذلك عادةً إلى أنّ العميل توقّف عن الانتظار. تحقَّق من مهلات انتهاء الوقت من جهة العميل.
2	500	`UNKNOWN`	حدث خطأ غير معروف. قد تتضمّن رسالة الخطأ أو التفاصيل مزيدًا من المعلومات.	التعامل معها كخطأ في الخادم يمكن غالبًا إعادة المحاولة مع التراجع.
3	400	`INVALID_ARGUMENT`	حدّد العميل وسيطة غير صالحة. يشير ذلك إلى مشكلة تمنع واجهة برمجة التطبيقات من معالجة الطلب، مثل اسم مورد غير صالح أو قيمة غير صالحة.	خطأ من جهة العميل: راجِع مَعلمات طلبك وتأكَّد من أنّها تستوفي متطلبات واجهة برمجة التطبيقات. تقدّم تفاصيل الخطأ عادةً معلومات حول الوسيط غير الصالح وطريقة ذلك، لذا استخدِم هذه التفاصيل لتصحيح الطلب. لا تعِد المحاولة بدون إصلاح الطلب.
4	504	`DEADLINE_EXCEEDED`	انتهت المهلة قبل أن تتمكّن العملية من الاكتمال.	خطأ في الخادم: غالبًا ما يكون عابرًا. ننصحك بإعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
5	404	`NOT_FOUND`	لم يتم العثور على بعض العناصر المطلوبة، مثل حملة أو مجموعة إعلانية.	خطأ في العميل: تحقَّق من توفّر الموارد التي تحاول الوصول إليها ومن معرّفاتها. لا تعِد المحاولة بدون تصحيح.
6	409	`ALREADY_EXISTS`	الكيان الذي حاول العميل إنشاءه موجود من قبل.	خطأ من جهة العميل: تجنَّب إنشاء موارد مكرّرة. تحقَّق مما إذا كان المرجع متوفّرًا قبل محاولة إنشائه.
7	403	`PERMISSION_DENIED`	ليس لدى المتصل إذن لتنفيذ العملية المحدّدة.	خطأ في العميل: يُرجى التحقّق من المصادقة والأذونات وأدوار المستخدمين في حساب "إعلانات Google". لا تعِد المحاولة بدون حلّ مشكلة الأذونات.
8	429	`RESOURCE_EXHAUSTED`	إما أن يكون المورد قد استُنفد (على سبيل المثال، تجاوزت الحصة المخصّصة لك)، أو أنّ النظام مثقل.	خطأ في العميل/الخادم: يتطلّب عادةً الانتظار. استخدِم الرقود الأسي الثنائي وقد تحتاج إلى خفض معدّل الطلبات. اطّلِع على حدود واجهة برمجة التطبيقات وحصصها.
9	400	`FAILED_PRECONDITION`	تم رفض العملية لأنّ النظام ليس في الحالة المطلوبة لتنفيذها. على سبيل المثال، لم يتم إدخال حقل مطلوب.	خطأ من جهة العميل: الطلب صالح، ولكن الحالة غير صحيحة. راجِع تفاصيل الخطأ لفهم سبب عدم استيفاء الشرط المسبق. لا تعِد المحاولة بدون تصحيح الحالة.
10	409	`ABORTED`	تم إلغاء العملية، وعادةً ما يكون ذلك بسبب مشكلة في التزامن، مثل تعارض المعاملات.	خطأ في الخادم: من الآمن غالبًا إعادة المحاولة مع تأخير قصير.
11	400	`OUT_OF_RANGE`	تمت محاولة إجراء العملية بعد انتهاء النطاق الصالح.	خطأ من جهة العميل: صحِّح النطاق أو الفهرس.
12	501	`UNIMPLEMENTED`	لم يتم تنفيذ العملية أو أنّ واجهة برمجة التطبيقات لا تتيحها.	خطأ في العميل: تحقَّق من إصدار واجهة برمجة التطبيقات والميزات المتاحة. لا تعِد المحاولة.
13	500	`INTERNAL`	حدث خطأ داخلي. هذا الردّ الجاهز هو ردّ عام وشامل على المشاكل المتعلّقة بجهة الخادم.	خطأ في الخادم: يمكن بشكل عام إعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي. إذا استمرّت المشكلة، يُرجى الإبلاغ عنها.
14	503	`UNAVAILABLE`	الخدمة غير متوفرة مؤقتًا. من المرجّح أن تكون هذه الحالة مؤقتة.	حدث خطأ في الخادم: يُنصح بشدة بإعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
15	500	`DATA_LOSS`	ثمة بيانات تالفة أو بيانات مفقودة ويتعذّر استرجاعها.	خطأ في الخادم: نادر. تشير إلى مشكلة خطيرة. لا تعِد المحاولة. إذا استمرّت المشكلة، يُرجى الإبلاغ عنها.
16	401	`UNAUTHENTICATED`	لا يتضمّن الطلب بيانات اعتماد مصادقة صالحة.	حدث خطأ في العميل: يُرجى التحقّق من رموز المصادقة وبيانات الاعتماد. لا تعِد المحاولة بدون حلّ مشكلة المصادقة.

لمزيد من التفاصيل حول هذه الرموز، يُرجى الرجوع إلى دليل تصميم واجهة برمجة التطبيقات - رموز الخطأ.

فهم تفاصيل الخطأ

بالإضافة إلى الرمز ذي المستوى الأعلى، تقدّم Google Ads API معلومات أكثر تحديدًا عن الخطأ ضمن الحقل details الخاص بالكائن Status. يحتوي هذا الحقل غالبًا على GoogleAdsFailure proto، والذي يتضمّن قائمة بعناصر GoogleAdsError فردية.

يحتوي كل عنصر GoogleAdsFailure على ما يلي:

errors: قائمة بعناصر GoogleAdsError، يقدّم كل منها تفاصيل خطأ معيّن حدث.
request_id: معرّف فريد للطلب، وهو مفيد لأغراض تصحيح الأخطاء والدعم.

يوفّر كل عنصر GoogleAdsError ما يلي:

error_code: رمز خطأ أكثر تفصيلاً خاصًا بواجهة Google Ads APIErrorCode (الأخطاء الشائعة)، مثل AuthenticationError.NOT_ADS_USER
‫message: وصف مفهوم للخطأ المحدّد.
trigger: تمثّل Value الذي تسبّب في حدوث الخطأ، إذا كان ذلك منطبقًا.
location: ErrorLocation يصف موضع حدوث الخطأ في الطلب، بما في ذلك مسارات الحقول.
details: ErrorDetails إضافي، مثل أسباب الخطأ غير المنشورة.

مثال على تفاصيل الخطأ

عند تلقّي خطأ، ستتيح لك مكتبة البرامج الوصول إلى هذه التفاصيل. على سبيل المثال، قد يتضمّن الرمز INVALID_ARGUMENT (الرمز 3) تفاصيل على النحو التالي: GoogleAdsFailure

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v25.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ],
      "requestId": "AbCdEfGhIjKlMnOpQrStUv"
    }
  ]
}

في هذا المثال، على الرغم من أنّ INVALID_ARGUMENT هو المستوى الأعلى، فإنّ تفاصيل GoogleAdsFailure توضّح لك أنّ الحقلَين name وdescription هما السبب في المشكلة وسببها (REQUIRED وTOO_SHORT على التوالي).

تحديد موقع تفاصيل الخطأ

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

طلبات البيانات العادية وطلبات البيانات المتدفقة من واجهة برمجة التطبيقات

عندما يتعذّر تنفيذ طلب بيانات من واجهة برمجة التطبيقات بدون استخدام ميزة "التعطُّل الجزئي"، بما في ذلك طلبات البث، يتم عرض الكائن GoogleAdsFailure كجزء من البيانات الوصفية اللاحقة في عناوين استجابة gRPC. إذا كنت تستخدم REST للمكالمات العادية، سيتم عرض GoogleAdsFailure في استجابة HTTP. تعرض مكتبات العملاء عادةً هذا الخطأ على أنّه استثناء مع السمة GoogleAdsFailure.

تعذُّر التنفيذ جزئيًا

في حال استخدام الفشل الجزئي، يتم عرض أخطاء العمليات الفاشلة في الحقل partial_failure_error ضمن الرد، وليس في عناوين الرد. في هذه الحالة، يتم تضمين GoogleAdsFailure ضمن عنصر google.rpc.Status في الردّ.

المهام المجمّعة

بالنسبة إلى المعالجة على دفعات، يمكن العثور على أخطاء العمليات الفردية من خلال استدعاء BatchJobService.ListBatchJobResults بعد اكتمال المهمة. سيتضمّن كل نتيجة عملية الحقل status الذي يحتوي على تفاصيل الخطأ في حال تعذّر إتمام العملية.

معرّف الطلب

request-id هي سلسلة فريدة تحدّد طلب بيانات من واجهة برمجة التطبيقات، وهي ضرورية لتحديد المشاكل وحلّها.

يمكنك العثور على request-id في عدة أماكن:

‫GoogleAdsFailure: إذا تعذّر تنفيذ طلب بيانات من واجهة برمجة التطبيقات وتم عرض GoogleAdsFailure، سيتضمّن request_id.
البيانات الوصفية اللاحقة: في كلّ من الطلبات الناجحة والفاشلة، يتوفّر request-id في البيانات الوصفية اللاحقة لردّ gRPC.
عناوين الاستجابة: لكل من الطلبات الناجحة والفاشلة، يتوفّر request-id أيضًا في عناوين استجابة gRPC واستجابة HTTP، باستثناء طلبات البث الناجحة.
SearchGoogleAdsStreamResponse: بالنسبة إلى طلبات البث، تحتوي كل رسالة SearchGoogleAdsStreamResponse على حقل request_id.

عند تسجيل الأخطاء أو التواصل مع فريق الدعم، احرص على تضمين request-id للمساعدة في تشخيص المشاكل.

أفضل الممارسات المتعلّقة بمعالجة الأخطاء

لإنشاء تطبيقات مرنة، اتّبِع أفضل الممارسات التالية:

فحص تفاصيل الخطأ: احرص دائمًا على تحليل الحقل details الخاص بالكائن Status، مع البحث تحديدًا عن GoogleAdsFailure. توفّر التفاصيل الدقيقة error_code وmessage وlocation ضمن GoogleAdsError المعلومات الأكثر فائدة لتصحيح الأخطاء وملاحظات المستخدمين.
التمييز بين أخطاء العميل وأخطاء الخادم:
- أخطاء العميل: رموز مثل INVALID_ARGUMENT وNOT_FOUND وPERMISSION_DENIED وFAILED_PRECONDITION وUNAUTHENTICATED تتطلّب هذه الأخطاء إجراء تغييرات على الطلب أو حالة/بيانات اعتماد تطبيقك. لا تعِد محاولة إرسال الطلب بدون حلّ المشكلة.
- أخطاء الخادم: رموز مثل UNAVAILABLE وINTERNAL وDEADLINE_EXCEEDED وUNKNOWN تشير هذه الرموز إلى حدوث مشكلة مؤقتة في خدمة واجهة برمجة التطبيقات.
تنفيذ استراتيجية إعادة المحاولة:
- وقت إعادة المحاولة: أعِد المحاولة فقط في حال حدوث أخطاء مؤقتة في الخادم، مثل UNAVAILABLE وDEADLINE_EXCEEDED وINTERNAL وUNKNOWN وABORTED.
- الرقود الأسي الثنائي: استخدِم خوارزمية الرقود الأسي الثنائي للانتظار لفترات زمنية متزايدة بين عمليات إعادة المحاولة. يساعد ذلك في تجنُّب إرهاق خدمة تعاني من ضغط كبير. على سبيل المثال، الانتظار لمدة ثانية واحدة، ثم ثانيتين، ثم 4 ثوانٍ، مع مواصلة الانتظار حتى الوصول إلى الحد الأقصى لعدد محاولات إعادة المحاولة أو إجمالي وقت الانتظار.
- التأخير العشوائي: أضِف مقدارًا صغيرًا عشوائيًا من "التأخير العشوائي" إلى فترات التأخير للحيلولة دون حدوث مشكلة "الازدحام" التي تحدث عندما يعيد العديد من العملاء المحاولة في الوقت نفسه.
تسجيل البيانات بدقة: سجِّل استجابة الخطأ الكاملة، بما في ذلك جميع التفاصيل، وخاصةً معرّف الطلب. هذه المعلومات ضرورية لتصحيح الأخطاء ولإبلاغ فريق الدعم في Google بالمشاكل عند الحاجة.
تقديم ملاحظات للمستخدمين: استنادًا إلى الرموز والرسائل المحدّدة GoogleAdsError، قدِّم ملاحظات واضحة ومفيدة لمستخدمي تطبيقك. على سبيل المثال، بدلاً من مجرد قول "حدث خطأ"، يمكنك قول "اسم الحملة مطلوب" أو "لم يتم العثور على رقم تعريف المجموعة الإعلانية المقدَّم".

من خلال اتّباع هذه الإرشادات، يمكنك تشخيص الأخطاء التي تعرضها واجهة برمجة التطبيقات Google Ads API والتعامل معها بفعالية، ما يؤدي إلى إنشاء تطبيقات أكثر استقرارًا وسهولة في الاستخدام.

أنواع الأخطاء

الأخطاء الشائعة

التعرّف على أخطاء واجهة برمجة التطبيقات تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.