لغة طلب البحث في 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
قائمة بالحقول مفصولة بفواصل لاستردادها.
يمكنك اختيار أي حقل من طريقة العرض التي تستخدمها. فيما يلي بعض الأمثلة على الحقول التي يمكنك تحديدها:
يمكنك إجراء طلبات بحث في أنواع متعددة من الحقول في طلب واحد. وفي ما يلي مثال لذلك:
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
راجِع القواعد النحوية للحصول على القائمة الكاملة للنطاقات الزمنية النسبية المتاحة.