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

ondemand_video فيديو: الاطّلاع على محاضرة عن "الخدمات والموارد" في ورشة عمل 2019

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

التدرّج الهرمي للكائنات

يمكن النظر إلى حساب "إعلانات Google" على أنّه تدرّج هرمي من العناصر.

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

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

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

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

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

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

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

الموارد

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

أرقام تعريف الكائنات

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

يمكن أن تكون قواعد المعرِّف هذه مفيدة عند تصميم مساحة تخزين محلية لحسابك على "إعلانات 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 متاح أيضًا في المستندات المرجعية للحقول.