تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

Merchant Center Query Language

لغة طلب البحث في Merchant Center (MCQL) هي لغة استعلام تشبه لغة الاستعلامات البنيوية (SQL). يمكنك استخدام الإعلانات المتعدّدة العملاء (MCQL) مع Merchant Reports API لاسترداد بيانات الأداء المتعلّقة بمنتجاتك والسوق التي تنافس فيها هذه المنتجات.

القواعد اللغوية

إليك المرجع النحوي لحقل MCQL (في تدوين التعبير العادي):

Query            -> SelectClause FromClause? WhereClause? OrderByClause? LimitClause?
SelectClause     -> SELECT FieldName (, FieldName)*
FromClause       -> FROM TableName
WhereClause      -> WHERE Condition (AND Condition)*
OrderByClause    -> ORDER BY Ordering (, Ordering)*
LimitClause      -> LIMIT PositiveInteger

Condition        -> FieldName Operator Value | FieldName BETWEEN Value AND Value
Operator         -> = | != | > | >= | < | <= | <> | IN | NOT IN |
                    CONTAINS ANY | CONTAINS ALL | CONTAINS NONE | DURING |
                    LIKE | NOT LIKE | REGEXP_MATCH | NOT REGEXP_MATCH
Value            -> Number | NumberList | String | StringList | Function
Ordering         -> FieldName (ASC | DESC)?

FieldName        -> [a-z] ([a-zA-Z0-9._])*
TableName        -> [A-Z] ([a-zA-Z_])*

StringList       -> ( String (, String)* )
NumberList       -> ( Number (, Number)* )

PositiveInteger  -> [1-9] ([0-9])*
Number           -> -? [0-9]+ (. [0-9] [0-9]*)?
String           -> (' Char* ') | (" Char* ")
Function         -> LAST_14_DAYS | LAST_30_DAYS | LAST_7_DAYS |
                    LAST_BUSINESS_WEEK | LAST_MONTH | LAST_WEEK_MON_SUN |
                    LAST_WEEK_SUN_SAT | THIS_MONTH | THIS_WEEK_MON_TODAY |
                    THIS_WEEK_SUN_TODAY | TODAY | YESTERDAY

يمكنك استخدام الرموز التالية:

يشير ? إلى عنصر اختياري.
* تعني صفر أو أكثر، و+ تعني واحدًا أو أكثر.
تشير السمة (xxxxxx) إلى مجموعة.
تشير السمة [a-z0-9] إلى نطاقات الأحرف.
يشير الاختصار | إلى "أو".

الحساسية لحالة الأحرف

معظم عوامل تشغيل MCQL حسّاسة لحالة الأحرف:

عوامل التشغيل	الحساسية لحالة الأحرف
= أو !=	حساس لحالة الأحرف
(ليس) الهند	حساس لحالة الأحرف
(لا) أعجبني	حساس لحالة الأحرف
يحتوي على (...)	حساس لحالة الأحرف
REGEXP_MATCH	كلا الخيارين اختياريين

العبارات

فيما يلي العبارات التي يمكنك الاستعلام عنها باستخدام MCQL:

SELECT

تأخذ العبارة SELECT قائمة بالحقول مفصولة بفواصل لاستردادها.

يمكنك اختيار أي حقل من طريقة العرض التي تستخدمها. فيما يلي بعض الأمثلة على الحقول التي يمكنك تحديدها:

المقاييس
- impressions
- clicks
الشرائح
- date
- marketingMethod

يمكنك إجراء طلبات بحث في أنواع متعددة من الحقول في طلب واحد. وفي ما يلي مثال لذلك:

SELECT
  date,
  marketingMethod,
  impressions,
  clicks
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'

مِن

تحدّد العبارة FROM الجدول الذي تريد جلب البيانات منه في الطلب. يمكنك تحديد حقل واحد فقط في عبارة FROM. تكون عبارة FROM مطلوبة لجميع طلبات البحث.

أين؟

يمكنك استخدام عبارة WHERE لفلترة البيانات المتوفّرة في طلبك. تكون عبارة WHERE مطلوبة لطلبات البحث عن الأداء. يمكنك الفلترة حسب جميع حقول الشرائح، وحسب حقول metrics الإضافية في حال تحديدها في عبارة SELECT.

في ما يلي مثال يستخدم السمة WHERE لعرض مرات الظهور من فترة زمنية محدّدة فقط (شهر آب/أغسطس):

SELECT offerId, impressions
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'

يمكنك الفلترة حسب شروط متعدّدة في طلب بحث واحد باستخدام عامل التشغيل AND. استخدِم AND بين الشروط الكاملة، مثل: WHERE marketingMethod != "ADS" AND marketingMethod != "ORGANIC". لا يمكنك استخدام AND بين القيم في شرط واحد، على سبيل المثال: WHERE marketingMethod != "ADS" AND "ORGANIC".

في ما يلي مثال يعرض عدد النقرات لكل عرض - حيث تم تسجيل أكثر من 100 نقرة - لطريقة التسويق ADS خلال شهر آب (أغسطس):

SELECT offerId, clicks
FROM ProductPerformanceView
WHERE clicks > 100
  AND marketingMethod = 'ADS'
  AND date BETWEEN '2020-08-01' AND '2020-08-31'

لا تتوافق عبارة WHERE مع لغة OR. تتأثر عوامل التشغيل بحالة الأحرف. للحصول على قائمة كاملة بعوامل التشغيل، راجِع grammar.

ORDER BY (اختياري)

تتيح لك العبارة ORDER BY استرداد النتائج بترتيب محدّد.

حدِّد الطلب باستخدام السمة fieldName، ثم ASC أو DESC. يمكنك فقط الترتيب حسب الحقول المحددة في عبارة SELECT من طلب البحث. يتم ضبط ORDER BY تلقائيًا على ASC في حال عدم تحديد قيمة معيّنة.

يرتب طلب البحث التالي الصفوف التي تم عرضها حسب عدد النقرات، من الأعلى إلى الأدنى:

SELECT offerId, clicks
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'
ORDER BY clicks DESC

يمكنك تحديد عدة حقول في العبارة ORDER BY باستخدام قائمة مفصولة بفواصل.

على سبيل المثال، يتمّ ترتيب نتائج طلب البحث التالي تصاعديًا حسب offerId، ثم بترتيب تنازلي حسب عدد مرّات الظهور، ثم بترتيب تنازلي حسب عدد النقرات:

SELECT offerId, impressions, clicks
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'
ORDER BY
  offerId,
  impressions DESC,
  clicks DESC

الحد

تسمح لك عبارة LIMIT بتحديد عدد النتائج المراد عرضها.

في ما يلي مثال يعرض 50 نتيجة فقط، حتى إذا توفّرت صفوف أكثر.

SELECT offerId, impressions
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'
ORDER BY impressions DESC
LIMIT 50

يمكنك استخدام الحقل pageSize للتعامل مع قوائم النتائج الطويلة.

النطاقات الزمنية

تتيح لك الإعلانات المتعدّدة العملاء (MCQL) تحديد نطاق زمني مخصّص أو نسبي. عليك استخدام عبارة WHERE لتحديد نطاق date لجميع طلبات الأداء.

قرض مخصص

يمكنك تحديد تواريخ ISO 8601(YYYY-MM-DD) بالتنسيقات التالية:

date BETWEEN '2021-01-01' AND '2021-01-31'
date >= '2021-01-01' AND date <= '2021-01-31'

يمكنك تحديد سلاسل التاريخ إما باستخدام علامات اقتباس مفردة (') أو علامات اقتباس مزدوجة (").

أحد الأقارب

يمكنك تحديد نطاق زمني نسبي، مثل LAST_30_DAYS أو THIS_MONTH، باستخدام DURING بدلاً من BETWEEN وAND:

WHERE date DURING LAST_30_DAYS

راجِع القواعد النحوية للحصول على القائمة الكاملة للنطاقات الزمنية النسبية المتاحة.