تُعد GoogleAdsService
خدمة موحَّدة لاسترداد العناصر وإعداد التقارير
من Google Ads API. تتضمن الخدمة طُرقًا:
- استرداد سمات محددة للكائنات.
- استرداد مقاييس الأداء للعناصر استنادًا إلى نطاق زمني
- ترتيب الكائنات بناءً على سماتها
- استخدام الشروط للإشارة إلى العناصر التي تريد عرضها في الاستجابة
- حدِّد عدد العناصر التي يتم عرضها.
يمكن أن تعرض GoogleAdsService
النتائج
بطريقتَين:
GoogleAdsService.SearchStream
يعرض جميع الصفوف في استجابة بث واحدة، وهو أكثر فعالية لمجموعات النتائج الكبيرة (الأكبر من 10,000 صف). قد يكون هذا أكثر ملاءمة إذا كان التطبيق المجمّع يريد تنزيل أكبر قدر ممكن من البيانات.- تقسّم
GoogleAdsService.Search
الردود الكبيرة إلى صفحات نتائج يمكن إدارتها. قد يكون هذا أكثر ملاءمة إذا كان تطبيقك التفاعلي يعرض صفحة من النتائج في كل مرة.
اطّلِع على مزيد من المعلومات حول نقل الصفحات مقابل البث.
تقديم طلب
تتطلّب طريقة البحث عنصر SearchGoogleAdsRequest
الذي يتكوّن من السمات التالية:
customer_id
- لغة طلب البحث في "إعلانات Google"
query
التي تشير إلى المورد المطلوب طلب البحث منه، والسمات والشرائح والمقاييس المطلوب استردادها، والشروط المطلوب استخدامها لتحديد العناصر التي يتم عرضها - (
GoogleAdsService.Search
فقط) Apage_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
.