جارٍ استرداد العناصر

تُعد 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.