فيديو: جلسة "الخدمات والمراجع" من ورشة العمل لعام 2019
يقدّم هذا الدليل المكوّنات الأساسية التي تشكّل Google Ads API. تتألف واجهة برمجة التطبيقات مع "إعلانات Google" من مراجع وخدمات. يمثّل المرجع عنصرًا في "إعلانات Google"، بينما تسترد الخدمات عناصر "إعلانات Google" وتعدّلها.
التدرّج الهرمي للعناصر
يمكن اعتبار حساب "إعلانات Google" تدرّجًا هرميًا للكائنات.
المورد ذو المستوى الأعلى في الحساب هو العميل.
يتضمّن كل عميل حملة واحدة أو أكثر من الحملات النشطة.
تحتوي كل حملة على مجموعة إعلانية واحدة أو أكثر، تُستخدَم لتجميع إعلاناتك في مجموعات منطقية.
يمثّل إعلان المجموعة الإعلانية إعلانًا تعرضه. باستثناء "حملات التطبيقات" التي يمكن أن تتضمّن إعلانًا واحدًا فقط للمجموعة الإعلانية لكل مجموعة إعلانية، تحتوي كل مجموعة إعلانية على إعلان واحد أو أكثر للمجموعة الإعلانية.
يمكنك إرفاق AdGroupCriterion
واحدة أو أكثر أو CampaignCriterion
بمجموعة إعلانية أو حملة. تمثّل هذه المعايير الطريقة التي يتم بها عرض الإعلانات.
هناك العديد من أنواع معايير الاستهداف، مثل الكلمات الرئيسية والفئات العمرية والمواقع الجغرافية. تؤثّر المعايير المحدّدة على مستوى الحملة في جميع الموارد الأخرى ضِمن الحملة. يمكنك أيضًا تحديد ميزانيات وتواريخ على مستوى الحملة.
أخيرًا، يمكنك إرفاق الإضافات على مستوى الحساب أو الحملة أو المجموعة الإعلانية. تسمح لك الإضافات بتقديم معلومات إضافية إلى إعلاناتك، مثل رقم الهاتف أو عنوان الشارع أو العروض الترويجية.
الموارد
تمثّل المراجع الكيانات داخل حسابك على "إعلانات Google". Campaign
وAdGroup
هما مثالان على الموارد.
أرقام تعريف العناصر
يتم تحديد كل عنصر في "إعلانات Google" من خلال معرّفه الخاص. بعض هذه المعرّفات فريدة على مستوى العالم في جميع حسابات "إعلانات Google"، بينما تكون المعرّفات الأخرى فريدة ضمن نطاق محدود فقط.
رقم تعريف العنصر | نطاق التفرّد | هل المعرّف فريد عالميًا؟ |
---|---|---|
معرِّف الميزانية | عالمي | نعم |
الرقم التعريفي للحملة | عالمي | نعم |
معرف المجموعة الإعلانية | عالمي | نعم |
معرّف الإعلان | المجموعة الإعلانية | لا، ولكنّ الزوج (AdGroupId ، AdId ) فريد على مستوى العالم |
رقم تعريف معيار المجموعة الإعلانية | المجموعة الإعلانية | لا، ولكنّ الزوج (AdGroupId ، CriterionId ) فريد على مستوى العالم |
رقم تعريف CampaignCriterion | الحملة | لا، ولكنّ الزوج (CampaignId , CriterionId ) فريد على مستوى العالم |
معلومات الإعلان الإضافية | الحملة | لا، ولكنّ الزوج (CampaignId , AdExtensionId ) فريد على مستوى العالم |
الرقم التعريفي للتصنيف | عالمي | نعم |
UserList ID | عالمي | نعم |
رقم تعريف مادة العرض | عالمي | نعم |
يمكن أن تكون قواعد المعرّفات هذه مفيدة عند تصميم مساحة تخزين محلية لعناصر "إعلانات 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
لتعديل الحملات
يجب أن يتضمّن كل طلب 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
أيضًا في المستندات المرجعية للحقول.