فيديو: الاطّلاع على حديث عن الخدمات والموارد من ورشة عمل 2019
يتناول هذا الدليل المكوّنات الأساسية التي تتألف منها واجهة برمجة التطبيقات Google Ads API. تتألّف واجهة برمجة التطبيقات مع "إعلانات Google" من موارد وخدمات. يمثل المورد كيان "إعلانات 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
. وتوفر أيضًا طلب 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
في المستندات المرجعية للحقول.