GoogleAdsService
عبارة عن خدمة موحّدة لاسترداد الكائنات وإعداد التقارير
في Google Ads API. تشتمل الخدمة على طرق:
- استرداد سمات معينة من الكائنات.
- يمكنك استرداد مقاييس الأداء للعناصر استنادًا إلى نطاق زمني.
- ترتيب الكائنات استنادًا إلى سماتها.
- استخدم الشروط للإشارة إلى الكائنات التي تريد عرضها في الاستجابة.
- تقييد عدد العناصر المعروضة
يمكن أن تعرض GoogleAdsService
النتائج بطريقتين:
GoogleAdsService.SearchStream
تعرض جميع الصفوف في استجابة بث واحدة، والتي تكون أكثر فعالية لمجموعات النتائج الكبيرة (التي تزيد عن 10000 صف). وقد يكون هذا هو الخيار الأفضل إذا كان التطبيق المجمّع يريد تنزيل أكبر قدر ممكن من البيانات.- يعمل
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