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

فيديو: مشاهدة حديث عن "الخدمات والموارد" من ورشة العمل لعام 2019

يقدم هذا الدليل المكوّنات الأساسية التي تشكّل Google Ads API. تتألّف واجهة Google Ads API من الموارد والخدمات. يمثّل المورد كيان "إعلانات Google"، بينما تسترد الخدمات كيانات "إعلانات Google" وتتعامل معها.

التسلسل الهرمي للكائنات

يمكن عرض حساب "إعلانات Google" كتسلسل هرمي للعناصر.

نموذج الحملة

  • المورد ذو المستوى الأعلى للحساب هو العميل.

  • لكل عميل حملة نشطة واحدة أو أكثر.

  • تحتوي كل حملة على مجموعة إعلانية واحدة أو أكثر تُستخدم لتجميع إعلاناتك في مجموعات منطقية.

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

يمكنك إرفاق عنصر AdGroupCriterion أو CampaignCriterion واحد أو أكثر بمجموعة إعلانية أو حملة. تمثّل هذه المعايير المعايير التي تحدِّد كيفية عرض الإعلانات.

هناك العديد من أنواع المعايير، مثل الكلمات الرئيسية والفئات العمرية والمواقع الجغرافية. تؤثر المعايير المحددة على مستوى الحملة على جميع الموارد الأخرى داخل الحملة. يمكنك أيضًا تحديد الميزانيات والتواريخ على مستوى الحملة

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

المراجِع

تمثّل الموارد العناصر ضمن حسابك على "إعلانات Google". Campaign وAdGroup هما مثالان على الموارد.

أرقام تعريف العناصر

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

رقم تعريف العنصر نطاق التفرد هل أنت فريد عالميًا؟
معرِّف الميزانية البلدان المتحدثة نعم
معرّف الحملة البلدان المتحدثة نعم
معرف المجموعة الإعلانية البلدان المتحدثة نعم
الرقم التعريفي للإعلان المجموعة الإعلانية لا، ولكن الزوج (AdGroupId، AdId) فريد عالميًا.
رقم تعريف معيار المجموعة الإعلانية المجموعة الإعلانية لا، ولكن الزوج (AdGroupId، CriterionId) فريد عالميًا.
رقم تعريف معيار الحملة الحملة لا، ولكن الزوج (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)

تعدّل هذه الخدمات المثيلات من نوع مورد مرتبط باستخدام طلب mutate. وتقدِّم أيضًا طلب get الذي يسترد مثيلاً واحدًا لمورد، ما قد يكون مفيدًا لفحص بنية مورد.

أمثلة على الخدمات:

يجب أن يتضمن كل طلب 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 أيضًا في المستندات المرجعية للحقول.