تُعد GoogleAdsService
خدمة موحَّدة لاسترداد العناصر وإعداد التقارير
في Google Ads API. تتضمن الخدمة طُرقًا ينطبق عليها ما يلي:
- استرداد سمات محددة للكائنات.
- استرداد مقاييس الأداء للعناصر استنادًا إلى نطاق زمني.
- ترتيب الكائنات استنادًا إلى سماتها
- استخدِم الشروط للإشارة إلى العناصر التي تريد عرضها في الاستجابة.
- حدِّد عدد العناصر التي يتم عرضها.
يمكن أن تعرض GoogleAdsService
النتائج بطريقتين، هما:
- تعرض العلامة
GoogleAdsService.SearchStream
جميع الصفوف في استجابة بث واحدة، وهي أكثر فعالية لمجموعات النتائج الكبيرة (التي تتجاوز 10,000 صف). قد يكون ذلك أكثر ملاءمة إذا كان التطبيق المجمّع يريد تنزيل أكبر قدر ممكن من البيانات. - تقسّم
GoogleAdsService.Search
الردود الكبيرة إلى صفحات نتائج يمكن إدارتها. قد يكون هذا أكثر ملاءمة إذا كان تطبيقك التفاعلي يعرض صفحة نتائج في كل مرة.
يمكنك الحصول على مزيد من المعلومات حول نقل الصفحات مقابل البث.
تقديم طلب
تتطلب طريقة البحث SearchGoogleAdsRequest
الذي يتكوّن من السمات التالية:
customer_id
- لغة طلب البحث في "إعلانات Google"
query
تشير إلى المورد المطلوب طلبه، والسمات والشرائح والمقاييس المطلوب استردادها، والشروط المطلوب استخدامها لتقييد العناصر التي يتم عرضها - (
GoogleAdsService.Search
فقط) أpage_size
للإشارة إلى عدد العناصر المطلوب عرضها في استجابة واحدة عند استخدام نقل الصفحات. - (
GoogleAdsService.Search
فقط) سمةpage_token
اختيارية لاسترداد المجموعة التالية من النتائج عند استخدام نقل الصفحات.
لمزيد من المعلومات عن لغة طلب البحث في "إعلانات Google"، راجِع دليل لغة طلب البحث في "إعلانات Google".
معالجة الرد
تعرض GoogleAdsService
قائمة بكائنات GoogleAdsRow
.
يمثّل كل GoogleAdsRow
عنصرًا يعرضه طلب بحث، ويتكون من مجموعة من السمات التي تتم تعبئتها استنادًا إلى الحقول المطلوبة في عبارة SELECT
. لا تتم تعبئة السمات غير المضمّنة في جملة SELECT
على كائنات GoogleAdsRow
في الاستجابة.
على سبيل المثال، مع أنّ السمة ad_group_criterion
تتضمّن السمة status
، لا تتم تعبئة الحقل status
للسمة ad_group_criterion
في الصف كاستجابة لطلب بحث لا تتضمّن فيه عبارة SELECT
العلامة ad_group_criterion.status
. وبالمثل، لا تتم تعبئة السمة campaign
للصف إذا لم تتضمن العبارة SELECT
أي حقول من مورد campaign
.
يمكن أن يحتوي كل GoogleAdsRow
على سمات ومقاييس مختلفة من صف آخر
في مجموعة النتائج نفسها، لذلك يجب النظر إلى الصفوف ككائنات بدلاً من
صفوف ثابتة في جدول.
أنواع تعداد غير معروفة
الموارد التي يتم عرضها من النوع UNKNOWN
غير متوافقة بشكل كامل في إصدار واجهة برمجة التطبيقات هذا. يمكن إنشاء هذه الموارد من خلال واجهات
أخرى مثل واجهة مستخدم "إعلانات Google". يمكنك اختيار المقاييس عندما يكون لأحد الموارد النوع UNKNOWN
، ولكن لا يمكنك تبديل المورد من خلال واجهة برمجة التطبيقات. ومن الأمثلة على ذلك حملة جديدة أو إعلان جديد يتم عرضه في واجهة المستخدم، ولكن
غير متاح في إصدار واجهة برمجة التطبيقات الذي تطلبه.
فيما يلي بعض الاعتبارات التي يجب مراعاتها:
- يمكن لاحقًا دعم مورد من النوع
UNKNOWN
أو البقاءUNKNOWN
إلى أجل غير مسمى. - يمكن أن تظهر العناصر الجديدة من النوع
UNKNOWN
في أي وقت. هذه الكائنات متوافقة مع الخلف لأن قيمة التعداد متوفرة بالفعل. ويتم تقديم الموارد مع هذا التغيير عند توافرها حتى يكون لديك عرض دقيق لحسابك. يمكن أن يظهر موردUNKNOWN
بسبب أنشطة جديدة في حسابك من خلال واجهات أخرى، أو إذا لم يعُد أحد الموارد متاحًا. - يمكن أن تحتوي موارد
UNKNOWN
على مقاييس تفصيلية مرفقة بها يمكن طلب البحث فيها. - تظهر موارد
UNKNOWN
عادةً بشكلٍ كامل في واجهة مستخدم "إعلانات Google". - لا يمكن تبديل موارد
UNKNOWN
بشكل عام.
التصنيف إلى قطاعات أو شرائح
سيحتوي الرد على سمة GoogleAdsRow
واحدة لكل مجموعة مما يلي:
- مثيل المورد الرئيسي المحدّد في البند
FROM
- قيمة كل حقل
segment
محدّد
على سبيل المثال، رد طلب بحث يختار FROM campaign
ويحتوي على segments.ad_network_type
وsegments.date
في عبارة SELECT
يجب أن يحتوي على صف واحد لكل مجموعة من ما يلي:
campaign
segments.ad_network_type
segments.date
يتم تقسيم النتائج ضمنيًا حسب كل مثيل من المورد الرئيسي، وليس حسب قيم الحقول الفردية المحدّدة. على سبيل المثال:
SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
ينتج عنها صف واحد لكل حملة، وليس صفًا واحدًا لكل قيمة مختلفة للحقل campaign.status
.