انتقل إلى المحتوى
تمايز للتسويق وتطوير المتاجر الإلكترونيةتقنية وتسويقالعودة للمتجر
القائمة

تمايز / معلومات تهمك

كيف تمنع تكرار عمليات Google Ads API عند انقطاع الرد؟

دليل عملي لتسجيل عمليات Google Ads API وفحص الحالة بعد انقطاع الرد، مع استخدام validate_only وpartial_failure دون تكرار الموارد.

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

تشرح وثائق Google Ads API لعمليات mutate الفرق بين العمليات المتزامنة والدفعات، وخيارات الذرية وpartial_failure وvalidate_only. وتوضح وثائق Shopify للطلبات المتكررة بأمان المبدأ العام لمفتاح التكرار في الواجهات التي تدعمه. هذا المصدر الثاني يشرح المفهوم، لكنه لا يعني أن Google Ads يقبل مفتاح Shopify؛ يجب تنفيذ آلية Google الموثقة مع سجل محلي وفحص الحالة.

لماذا تحدث العمليات المكررة في Google Ads API؟

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

افصل في قاعدة العمل بين ثلاث حالات: pending قبل الإرسال، وconfirmed بعد رد واضح ومعرّف محفوظ، وuncertain عند انتهاء الاتصال دون رد حاسم. حالة uncertain ليست فشلًا نهائيًا ولا تفويضًا بإعادة التنفيذ؛ هي إشارة لقراءة الحساب أولًا.

كيف تستخدم validate_only والذرية؟

قبل تنفيذ مجموعة تغييرات جديدة، استخدم validate_only عندما تكون العملية تدعمه لاكتشاف أخطاء الحقول والسياسات من دون حفظ التعديل. هذا لا يثبت نجاح التنفيذ اللاحق، لكنه يقلل الأخطاء التي يمكن كشفها مسبقًا.

بحسب وثائق Google، تنفذ عملية mutate افتراضيًا كوحدة واحدة عندما يكون partial_failure غير مفعّل: إذا أخفقت عملية، لا تُحفظ المجموعة. عند تفعيل partial_failure قد تنجح بعض العمليات وتفشل أخرى، لذلك يجب قراءة نتيجة كل عملية وحفظ معرّفات الناجح منها. لا تعامل استجابة جزئية كنجاح كامل، ولا تعيد إرسال الدفعة كلها لأن ذلك قد يكرر العناصر التي نجحت.

خطوات معالجة انقطاع الرد دون تكرار

  1. أنشئ requestId داخليًا قبل الإرسال، واربطه بالحساب ونوع العملية وبصمة الحقول المطلوبة.
  2. احفظ الحالة pending ثم أرسل الطلب مرة واحدة، مع الاحتفاظ بأسماء الموارد المؤقتة أو المفاتيح التجارية التي تساعد على البحث.
  3. إذا وصل رد ناجح، احفظ أسماء الموارد التي أعادها Google وحوّل الحالة إلى confirmed.
  4. إذا انقطع الرد، غيّر الحالة إلى uncertain ولا تنشئ طلبًا جديدًا فورًا.
  5. اقرأ الموارد في الحساب وابحث بالاسم والمعرّفات والوقت والحقول المقصودة. إذا وجدت نتيجة مطابقة، اربطها بالطلب القديم واحفظها كمؤكدة.
  6. إذا أثبتت القراءة عدم التنفيذ، أعد المحاولة ضمن سياسة محددة وسجلها تحت requestId نفسه، مع منع عاملين من معالجة السجل في الوقت ذاته.
  7. في partial_failure أعد فقط العمليات الفاشلة صراحة، واترك الموارد الناجحة بمعرّفاتها المحفوظة.

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

مثال افتراضي

مثال افتراضي: أرسل نظام متجر عملية تنشئ حملة ومجموعة إعلانية وإعلانًا، ثم انتهت مهلة الاتصال. يسجل النظام العملية uncertain بدل «فشل». عند القراءة يجد حملة بالاسم المخطط ووقت إنشاء قريب، ويتحقق من الميزانية ونوع القناة ثم يحفظ اسم المورد. إذا كانت المجموعة مفقودة لأن الطلب استخدم partial_failure، يعيد العملية الناقصة وحدها بعد التأكد من اعتمادها على الحملة الموجودة.

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

الفرق بين مفتاح التكرار وسجل العمليات

واجهة تدعم مفتاح idempotency تتعرف إلى الإعادة بالمفتاح نفسه. لكن لا يجوز افتراض وجود هذا السلوك في كل API. وثائق Shopify مثال واضح على ضرورة استخدام المفتاح نفسه للطلب المكرر، وعلى أن مفتاحًا جديدًا يجعل الطلب مختلفًا. في تكامل Google Ads اعتمد فقط الميزات الموثقة هناك، وأضف سجلًا محليًا يثبت القصد والنتيجة.

البصمة المحلية لا تمنع Google من التنفيذ تلقائيًا؛ هي تمنع تطبيقك من إرسال عملية ثانية قبل التحقق. اجعلها تشمل الحساب ونوع المورد والحقول الجوهرية، ولا تضع أسرار المصادقة في السجل.

قائمة مراجعة قبل تشغيل الأتمتة

  • هل لكل عملية requestId داخلي ثابت؟
  • هل تفرّق بين failed وuncertain؟
  • هل تحفظ أسماء الموارد من الرد الحقيقي؟
  • هل تستخدم validate_only حيث تدعمه العملية؟
  • هل تعرف أثر partial_failure على كل عنصر؟
  • هل تمنع عاملين من معالجة الطلب نفسه؟
  • هل تقرأ الحساب قبل إعادة أي إنشاء غير مؤكد؟
  • هل تعيد العناصر الفاشلة فقط في الاستجابة الجزئية؟

القاعدة الآمنة هي أن غياب الرد لا يساوي غياب التنفيذ. القراءة والمطابقة وحفظ الإيصال الحقيقي تسبق أي إعادة، خصوصًا عندما تنشئ العملية موارد جديدة.

المراجع والمصادر

محتوى إرشادي أُعد بمساعدة الذكاء الاصطناعي. الأمثلة افتراضية للتوضيح، وليست نتائج لعملاء تمايز.

نسمعك

اكتب سؤالك أو ملاحظتك. يُنشر التعليق بعد المراجعة، ويبقى البريد خاصًا.