بنية طلب البحث

يمكن إرسال طلبات البحث عن حقول المقاييس والشرائح إلى طريقة reports.search. لإنشاء طلب بحث في Merchant Center Query Language، عليك أولاً إنشاء طلب البحث باستخدام قواعد اللغة. يتألف طلب البحث من عدد من العبارات:

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT

تستخدِم العبارات أسماء الحقول وأسماء الجداول وعوامل التشغيل والشروط وعمليات الترتيب لمساعدتك في اختيار البيانات المطلوبة. بعد الدمج في طلب بحث واحد، يمكن تقديم طلب باستخدام Google Content API for Shopping. لنلقِ نظرة على كيفية استخدام كل عبارة.

العبارات

SELECT

تحدّد العبارة SELECT مجموعة من الحقول المطلوب استردادها في الطلب. SELECT تتلقّى هذه الطريقة قائمة مفصولة بفواصل تتضمّن حقول شرائح ومقاييس، وتعرض القيم في الردّ. بند SELECT مطلوب في الاستعلام.

في ما يلي نموذج استعلام يختار مقاييس النقرات من جدول معيّن:

SELECT
  metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’

يمكنك أيضًا طلب أنواع مختلفة من الحقول في طلب واحد:

SELECT
  segments.date,
  segments.program,
  metrics.impressions,
  metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’

• حقول الشرائح

  • segments.date
  • segments.program

• المقاييس

  • metrics.impressions
  • metrics.clicks

لا يُسمح ببعض الحقول في عبارة SELECT بسبب القيود التالية:

• طلب البحث عن حقول الشرائح بدون حقل مقياس واحد على الأقل

يمكنك العثور على معلومات ذات صلة بالحالة المذكورة أعلاه في مستنداتنا المرجعية.

FROM

تحدّد العبارة FROM الجدول الذي سيتم جلب البيانات منه في الطلب. يحدّد الجدول في العبارة FROM الحقول التي يمكن أن تستخدمها جميع العبارات الأخرى لطلب البحث المحدّد. يمكن تحديد جدول واحد فقط في عبارة FROM. في الوقت الحالي، لا يتوفّر سوى جدول MerchantPerformanceView. إنّ عبارة FROM مطلوبة في طلب بحث إلى طريقة search في خدمة reports.

أين؟

تحدّد عبارة WHERE الشروط التي يجب تطبيقها عند فلترة البيانات للطلب. عند استخدام عبارة WHERE، يمكن تحديد شرط واحد أو أكثر باستخدام AND للفصل بينها. يجب أن يتّبع كل شرط النمط field_name Operator value. يمكن استخدام أي حقل من حقول الشرائح في عبارة WHERE، ولكن يجب تحديد حقول المقاييس في عبارة SELECT لاستخدامها في عبارة WHERE. إنّ عبارة WHERE مطلوبة في طلب البحث، لأنّه يجب دائمًا تحديد النطاق الزمني الذي تريد أن يتم عرض بيانات الأداء الخاصة بك فيه.

في ما يلي مثال على استخدام WHERE لعرض مقاييس من فترة زمنية محدّدة:

SELECT
  segments.offer_id,
  metrics.impressions
FROM MerchantPerformanceView
WHERE segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’

يمكنك الجمع بين شروط متعددة لفلترة البيانات. سيعرض هذا المثال عدد النقرات لكل عرض في برنامج SHOPPING_ADS حيث يكون عدد النقرات أكبر من 100 خلال فترة الـ 30 يومًا المحدّدة.

SELECT
  segments.offer_id,
  segments.program,
  metrics.clicks
FROM MerchantPerformanceView
WHERE metrics.clicks > 100
  AND segments.program = SHOPPING_ADS
  AND segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’;

في طلب البحث التالي، ستلاحظ أنّه تم اختيار segments.date. بغض النظر عمّا إذا اخترت segments.date، يجب دائمًا تقديم نطاق زمني محدود في عبارة WHERE لاسترداد بيانات الأداء.

SELECT
  segments.date,
  metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’

عند الفلترة، من المهم مراعاة حساسية عامل التشغيل لحالة الأحرف.

للحصول على قائمة كاملة بعوامل التشغيل، راجِع قواعد اللغة.

ORDER BY

تحدّد العبارة ORDER BY ترتيب عرض النتائج. يتيح لك ذلك ترتيب البيانات بترتيب تصاعدي أو تنازلي استنادًا إلى اسم حقل. يتم تحديد كل ترتيب على أنّه field_name متبوعًا بـ ASC أو DESC. إذا لم يتم تحديد ASC أو DESC، يكون الترتيب التلقائي هو ASC. لا يمكن استخدام سوى الحقول المحدّدة في عبارة SELECT في عبارة ORDER BY. يكون البند ORDER BY اختياريًا في الاستعلام.

يرتّب الاستعلام التالي الصفوف التي تم إرجاعها حسب عدد النقرات من الأعلى إلى الأدنى:

SELECT
  segments.offer_id,
  metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’
ORDER BY metrics.clicks DESC

يمكنك تحديد حقول متعددة في عبارة ORDER BY باستخدام قائمة مفصولة بفواصل. سيتم الترتيب بالتسلسل نفسه المحدّد في طلب البحث. على سبيل المثال، في طلب البحث هذا، سيتم ترتيب النتائج تصاعديًا حسب offer_id، ثم تنازليًا حسب عدد مرّات الظهور، ثم تنازليًا حسب عدد النقرات:

SELECT
  segments.offer_id,
  metrics.impressions,
  metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’
ORDER BY
  segments.offer_id,
  metrics.impressions DESC,
  metrics.clicks DESC

LIMIT

تتيح لك عبارة LIMIT تحديد عدد النتائج المطلوب عرضها. يكون هذا الإجراء مفيدًا إذا كنت مهتمًا بالحصول على ملخّص فقط.

على سبيل المثال، يمكن استخدام LIMIT لتقييد إجمالي عدد النتائج للاستعلام التالي:

SELECT
  segments.program,
  segments.offer_id,
  metrics.impressions
FROM MerchantPerformanceView
WHERE segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’
ORDER BY metrics.impressions DESC
LIMIT 50