فيديو: يمكنك الاطّلاع على محادثة الخدمات والموارد من ورشة العمل لعام 2019
يقدّم هذا الدليل المكوّنات الأساسية التي تشكّل Google Ads API. تتألّف واجهة برمجة التطبيقات Google Ads API من موارد وخدمات. يمثّل المورد ملفًا شخصيًا في "إعلانات Google"، في حين تسترجع الخدمات ملفات "إعلانات Google" الشخصية وتُجري عليها تعديلات.
التدرّج الهرمي للعناصر
يمكن عرض حساب "إعلانات Google" على أنّه تسلسل هرمي للكائنات.
المرجع من المستوى الأعلى للحساب هو العميل.
يحتوي كل عميل على حملة نشطة واحدة أو أكثر.
تحتوي كل حملة على مجموعة إعلانية واحدة أو أكثر، تُستخدَم لتجميع إعلاناتك في مجموعات منطقية.
يمثّل إعلان المجموعة الإعلانية إعلانًا يتم بثّه. باستثناء حملات التطبيقات التي يمكن أن تتضمّن إعلان مجموعة إعلانية واحدًا فقط لكل مجموعة إعلانية، تحتوي كل مجموعة إعلانية على إعلان مجموعة إعلانية واحد أو أكثر.
يمكنك إرفاق AdGroupCriterion
أو CampaignCriterion واحد أو أكثر بمجموعة إعلانية أو
حملة. وهي تمثّل معايير تحدّد كيفية بدء عرض الإعلانات.
هناك العديد من أنواع المعايير، مثل الكلمات الرئيسية وشرائح العمر والمواقع الجغرافية. تؤثر المعايير المحدّدة على مستوى الحملة في جميع الموارد الأخرى ضمن الحملة. يمكنك أيضًا تحديد الميزانيات والتواريخ على مستوى الحملة.
أخيرًا، يمكنك إرفاق الإضافات على مستوى الحساب أو الحملة أو المجموعة الإعلانية. تسمح لك الإضافات بتقديم معلومات إضافية في إعلاناتك، مثل رقم الهاتف أو عنوان الشارع أو العروض الترويجية.
الموارد
تمثّل المراجع الكيانات ضمن حسابك على "إعلانات Google". Campaign وAdGroup هما مثالان
على الموارد.
أرقام تعريف العناصر
يتم تحديد كل عنصر في "إعلانات Google" من خلال معرّفه الخاص. وتكون بعض هذه المعرّفات فريدة على مستوى جميع حسابات "إعلانات Google"، في حين تكون أخرى فريدة في نطاقها محدود فقط.
| رقم تعريف العنصر | نطاق التميز | هل هو فريد على مستوى العالم؟ |
|---|---|---|
| معرِّف الميزانية | عالمي | نعم |
| رقم تعريف الحملة | عالمي | نعم |
| معرف المجموعة الإعلانية | عالمي | نعم |
| الرقم التعريفي للإعلان | المجموعة الإعلانية | لا، ولكنّ الزوج (AdGroupId, AdId) فريد على مستوى العالم. |
| رقم تعريف معيار المجموعة الإعلانية | المجموعة الإعلانية | لا، ولكنّ الزوج (AdGroupId, CriterionId) فريد على مستوى العالم. |
| رقم تعريف CampaignCriterion | الحملة | لا، ولكنّ الزوج (CampaignId, CriterionId) فريد على مستوى العالم. |
| معلومات الإعلان الإضافية | الحملة | لا، ولكنّ الزوج (CampaignId, AdExtensionId) فريد على مستوى العالم. |
| الرقم التعريفي للخلاصة | عالمي | نعم |
| الرقم التعريفي لعنصر الخلاصة | عالمي | نعم |
| رقم تعريف سمة الخلاصة | الخلاصة | لا |
| رقم تعريف تعيين الخلاصة | عالمي | نعم |
| الرقم التعريفي للتصنيف | عالمي | نعم |
| رقم تعريف قائمة المستخدمين | عالمي | نعم |
يمكن أن تكون قواعد المعرّفات هذه مفيدة عند تصميم مساحة تخزين محلية لعناصر "إعلانات Google".
يمكن استخدام بعض الكائنات لأنواع متعددة من الكيانات. في هذه الحالات، يحتوي العنصر
على حقل type يصف محتوياته. على سبيل المثال، يمكن أن يشير الرمز
AdGroupAd إلى عنصر مثل إعلان نصي أو
إعلان فندق أو إعلان محلي. يمكن الوصول إلى هذه القيمة من خلال الحقل
AdGroupAd.ad.type، وهي تعرِض قيمة في التعداد
AdType.
أسماء الموارد
يتم تحديد كل مورد بشكل فريد من خلال سلسلة resource_name، التي
تسلسل المورد وعناصره الرئيسية في مسار. على سبيل المثال، تكون أسماء موارد
الحملة على النحو التالي:
customers/customer_id /campaigns/campaign_id
بالنسبة إلى حملة تحمل الرقم التعريفي 987654 في حساب "إعلانات Google" الذي يحمل الرقم التعريفي للعميل
1234567، سيكون resource_name على النحو التالي:
customers/1234567/campaigns/987654
الخدمات
تتيح لك الخدمات استرداد عناصر "إعلانات Google" وتعديلها. هناك ثلاثة أنواع من الخدمات: تعديل وخدمات استرداد العناصر والإحصاءات وخدمات استرداد بيانات التعريف.
تعديل (تحوُّل) العناصر
تعدِّل هذه الخدمات نُسخًا من نوع مورد مرتبط باستخدام طلب mutate. وتوفّر هذه الخدمات أيضًا طلب get يسترجع مثيلًا واحدًا من موارد
، ما قد يكون مفيدًا لفحص بنية أحد الموارد.
أمثلة على الخدمات:
CustomerServiceلتعديل العملاء.CampaignServiceلتعديل الحملات.AdGroupServiceلتعديل المجموعات الإعلانية.
يجب أن يتضمّن كل طلب mutate عناصر operation المقابلة. على سبيل المثال، تتوقع طريقة CampaignService.MutateCampaigns مثيلًا واحدًا أو أكثر
من CampaignOperation. اطّلِع على مقالة تغيير العناصر وفحصها للحصول على مناقشة تفصيلية عن العمليات.
عمليات التحويل المتزامنة
لا يمكن تعديل عنصر في "إعلانات Google" بشكل متزامن من خلال أكثر من مصدر واحد. وقد يؤدي ذلك إلى ظهور أخطاء إذا كان لديك مستخدمون متعدّدون يعدّلون العنصر نفسه باستخدام تطبيقك، أو إذا كنت تُغيّر عناصر "إعلانات Google" بشكل موازٍ باستخدام خيوط برمجية متعدّدة. ويشمل ذلك تعديل العنصر من سلاسل محادثات متعددة في التطبيق نفسه أو من تطبيقات مختلفة (مثل تطبيقك وجلسة واجهة مستخدم "إعلانات Google" في الوقت نفسه).
لا توفّر واجهة برمجة التطبيقات طريقة لقفل عنصر قبل تعديله. إذا حاول مصدران
إجراء تغيير على عنصر في الوقت نفسه، تُرسِل واجهة برمجة التطبيقات DatabaseError.CONCURRENT_MODIFICATION_ERROR.
عمليات التحويل غير المتزامنة مقابل عمليات التحويل المتزامنة
طرق التحويل في Google Ads API تكون متزامنة. لا تُعرِض طلبات البيانات من واجهة برمجة التطبيقات أيّ ردّ إلا بعد تغيير العناصر، ما يتطلّب منك الانتظار للحصول على ردّ بشأن كل طلب. على الرغم من أنّ هذا النهج سهل نسبيًا في الترميز، إلا أنّه قد يؤدي إلى التأثير سلبًا في موازنة التحميل وإهدار الموارد إذا تم إجبار العمليات على الانتظار إلى أن تكتمل المكالمات.
هناك نهج بديل وهو تغيير حالة العناصر بشكل غير متزامن باستخدام
BatchJobService، الذي يُجري دفعات من
العمليات على خدمات متعدّدة بدون انتظار اكتمالها. بعد إرسال مهمة معالجة ملف دفعي، تنفِّذ خوادم Google Ads API العمليات بشكل غير متزامن، ما يؤدي إلى تحرير العمليات لتنفيذ عمليات أخرى. يمكنك التحقّق من حالة التحميل بشكل دوري لمعرفة ما إذا اكتمل.
اطّلِع على دليل المعالجة المجمّعة للحصول على مزيد من المعلومات عن المعالجة بدون تسلسل.
التحقّق من التغيير
يمكن التحقّق من صحة معظم طلبات التعديل بدون تنفيذ الطلب فعليًا باستخدام بيانات حقيقية. يمكنك اختبار الطلب بحثًا عن المَعلمات غير المتوفّرة وقيم الحقل غير الصحيحة بدون تنفيذ العملية فعليًا.
لاستخدام هذه الميزة، اضبط الحقل الاختياري validate_only المنطقي للطلب على
true. سيتم بعد ذلك التحقّق من الطلب بالكامل كما لو كان سيتم تنفيذه، ولكن يتم تخطّي التنفيذ النهائي. في حال عدم العثور على أي أخطاء، يتم عرض ردّ
فارغ. إذا تعذّر إكمال عملية التحقّق، ستشير رسائل الخطأ في الردّ إلى نقاط الخطأ.
validate_only مفيد بشكل خاص في اختبار الإعلانات بحثًا عن الانتهاكات الشائعة للسياسة. يتم رفض الإعلانات تلقائيًا إذا كانت تنتهك السياسات، مثل استخدام كلمات أو علامات ترقيم أو أحرف كبيرة أو طول معيّن. يمكن أن يؤدي إعلان واحد غير صالح
إلى تعذُّر إتمام دفعة كاملة. يمكن أن يؤدي اختبار إعلان جديد ضمن validate_only
طلب إلى الكشف عن أيّ من هذه الانتهاكات. يمكنك الرجوع إلى مثال الرمز البرمجي للتعامل مع أخطاء انتهاك السياسة للاطّلاع على كيفية تطبيق ذلك.
الحصول على إحصاءات عن العناصر والأداء
GoogleAdsService هي الخدمة الوحيدة والمنسّقة
لاسترداد العناصر وإحصاءات الأداء.
تتطلّب جميع طلبات Search وSearchStream في GoogleAdsService طلب بحث يحدّد المورد الذي سيتم
البحث عنه، وسمات المورد ومقاييس الأداء التي سيتم استرجاعها،
والعبارات التي سيتم استخدامها لفلترة الطلب، والشرائح التي سيتم استخدامها لمزيد من
تقسيم إحصاءات الأداء. لمزيد من المعلومات عن تنسيق طلب البحث،
اطّلِع على دليل لغة طلب البحث في "إعلانات Google".
استرداد البيانات الوصفية
يسترجع GoogleAdsFieldService
البيانات الوصفية عن الموارد في Google Ads API، مثل السمات المتاحة لأحد
الموارد ونوعه.
تقدّم هذه الخدمة المعلومات اللازمة لإنشاء طلب بحث موجَّه إلى
GoogleAdsService. من باب التسهيل، تتوفّر أيضًا
المعلومات التي يعرضها الإجراء
GoogleAdsFieldService
في المستندات المرجعية للحقول.