يمكن إرسال طلبات البحث لحقول الموارد والشرائح والمقاييس إلى
GoogleAdsService
بحث أو SearchStream
الطرق. لإنشاء طلب بحث بلغة طلب البحث في "إعلانات Google"، ستحتاج إلى إنشائه باستخدام
قواعد اللغة يتكون الاستعلام من عدد من
على النحو التالي:
SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS
تستخدم البنود أسماء الحقول وأسماء الموارد وعوامل التشغيل والشروط الترتيبات لمساعدتك في تحديد البيانات الصحيحة. بعد دمجها في حملة واحدة استعلام، يمكن إجراء طلب باستخدام Google Ads API.
البنود
SELECT
تحدّد العبارة SELECT
مجموعة من الحقول المطلوب استرجاعها في الطلب.
تأخذ SELECT
قائمة مفصولة بفواصل من حقول الموارد، وحقول الشرائح،
والمقاييس، ليتم عرض القيم في الرد. عبارة SELECT
هي
مطلوبة في طلب البحث
يوضح نموذج الطلب أدناه مثالاً لاختيار السمات لطلب البحث المحدد المصدر:
SELECT
campaign.id,
campaign.name
FROM campaign
يمكنك طلب أنواع مختلفة من الحقول في طلب واحد، مثل:
SELECT
campaign.id,
campaign.name,
bidding_strategy.id,
bidding_strategy.name,
segments.device,
segments.date,
metrics.impressions,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
حقول الموارد
campaign.id
campaign.name
حقول الموارد
bidding_strategy.id
bidding_strategy.name
حقول الشرائح
segments.device
segments.date
المقاييس
metrics.impressions
metrics.clicks
قد لا يُسمح ببعض الحقول في عبارة SELECT
بسبب ما يلي:
القيود:
- حقول طلب البحث غير القابلة للاختيار. سيكون لهذه الحقول
تم وضع علامة
false
على سمة البيانات الوصفيةSelectable
. - اختيار سمات الحقول المتكرّرة سيكون لهذه الحقول
تم وضع علامة
true
على سمة البيانات الوصفيةisRepeated
. - جارٍ اختيار الحقول غير المتاحة للمورد المحدّد في
FROM
بند واحد. لا يمكن تحديد سمات بعض الموارد معًا، بل يمكن أيضًا ستكون مجموعة فرعية من جميع المقاييس والشرائح متاحة للمورد فيFROM
. - اختيار شرائح أو مقاييس لا تتوافق مع بعضها البعض. بالنسبة المزيد من المعلومات حول هذا الموضوع، راجع .
يمكن العثور على المعلومات المتعلّقة بالشروط المذكورة أعلاه في مستنداتنا المرجعية.
أو من GoogleAdsFieldService
.
FROM
تحدّد العبارة FROM
المورد الرئيسي الذي سيتم عرضه. تشير رسالة الأشكال البيانية
في عبارة FROM
يحدد الحقول التي يمكن استخدامها مع كل
العبارات للاستعلام المحدد. يمكن تحديد مورد واحد فقط في
FROM
. العبارة FROM
مطلوبة في طلب البحث
GoogleAdsService
بحث أو SearchStream
على الرغم من ذلك، يجب عدم تحديدها عند استخدام
GoogleAdsFieldService
يمكن أن يتوفّر مورد واحد فقط في عبارة FROM
لطلب بحث معيّن، إلا أنّ الحقول
من "الموارد المشار إليها" متوفرة أيضًا. هذه الموارد
بشكل ضمني مع المورد في عبارة FROM
، لذلك ما عليك سوى
تضيف سماتها إلى عبارة SELECT
لإرجاع قيمها. قد لا يتلقّى
الموارد على "موارد مصدر". في المثال التالي، يمكنك طلب
كل من رقم تعريف المجموعة الإعلانية ورقم تعريف الحملة من المجموعات الإعلانية:
SELECT
campaign.id,
ad_group.id
FROM ad_group
يتم دائمًا عرض الحقل resource_name
للمورد الرئيسي.
في المثال التالي، سيتم تضمين ad_group.resource_name
في السمة
رد على الرغم من عدم تحديده بشكل صريح في طلب البحث:
SELECT ad_group.id
FROM ad_group
وينطبق الشيء نفسه على الموارد الأخرى عند تحديد حقل واحد على الأقل.
على سبيل المثال: سيتم تضمين campaign.resource_name
في الرد على
الاستعلام التالي:
SELECT
campaign.id,
ad_group.id
FROM ad_group
أين؟
تحدّد العبارة WHERE
الشروط التي يجب تطبيقها عند فلترة البيانات حسب
طلبك. عند استخدام عبارة WHERE
، يمكن تحديد شرط واحد أو أكثر.
نستخدم AND
للفصل بينها. يجب أن يتبع كل شرط النمط
field_name Operator value
تعتبر عبارة WHERE
اختيارية في الاستعلام.
في ما يلي مثال على استخدام WHERE
لعرض مقاييس في وقت معيّن.
المدة:
SELECT
campaign.id,
campaign.name,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
يمكنك الجمع بين شروط متعددة لفلترة البيانات. هذا المثال سوف طلب عدد النقرات لجميع الحملات التي حققت مرات ظهور على الجوّال في آخر 30 يومًا.
SELECT
campaign.id,
campaign.name,
segments.device,
metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
AND segments.device = MOBILE
AND segments.date DURING LAST_30_DAYS
يجب أن تكون الشرائح في الفقرة WHERE
ضمن العبارة SELECT
، مع السمة
شرائح التاريخ التالية، والتي يُشار إليها باسم شرائح التاريخ الأساسي
الاستثناءات:
segments.date
segments.week
segments.month
segments.quarter
segments.year
في طلب البحث التالي، لاحظ أنه تم اختيار segments.date
.
بما أنّ هذا القسم هو جزء من التاريخ الأساسي، يجب تحديد تاريخ محدَّد.
نطاق مكون من شرائح التاريخ الأساسي في عبارة WHERE
المراد تقديمها.
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
جميع الشرائح التي تستوفي الشرط السابق هي: segments.date, channels.week,
segmentation.month وSegment.quarter وsegments.year. إذا كان أي من هذه الشرائح
محدّدة، يجب استخدام واحد منها على الأقل في عبارة WHERE
.
عند الفلترة، من المهم مراعاة حساسية حالة الأحرف بالنسبة إلى عامل التشغيل الذهن. راجِع الحساسية لحالة الأحرف للحصول على المزيد من التفاصيل.
للحصول على قائمة كاملة بعوامل التشغيل، يُرجى الرجوع إلى اللغة. النحوية
ORDER BY
تحدّد العبارة ORDER BY
الترتيب الذي ستظهر به النتائج.
عاد. يتيح لك ذلك ترتيب البيانات تصاعديًا أو تنازليًا
بناءً على اسم الحقل. يتم تحديد كل طلب على أنّه field_name
متبوعًا
ASC
أو DESC
. إذا لم يتم تحديد ASC
أو DESC
، سيتم ضبط الطلب تلقائيًا.
إلى ASC
. تعتبر عبارة ORDER BY
اختيارية في الاستعلام.
يرتب الاستعلام التالي الحملات المعروضة حسب عدد النقرات من الأعلى إلى الأدنى:
SELECT
campaign.name,
metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC
يمكنك تحديد حقول متعددة في عبارة ORDER BY
باستخدام مفصولة بفواصل.
الحالية. سيحدث الترتيب بالتسلسل نفسه المحدد في طلب البحث.
على سبيل المثال، في طلب البحث هذا عند تحديد بيانات المجموعة الإعلانية، سيتم ترتيب النتائج.
بترتيب تصاعدي حسب اسم الحملة، ثم بترتيب تنازلي حسب عدد
لمرات الظهور، ثم بترتيب تنازلي حسب عدد النقرات:
SELECT
campaign.name,
ad_group.name,
metrics.impressions,
metrics.clicks
FROM ad_group
ORDER BY
campaign.name,
metrics.impressions DESC,
metrics.clicks DESC
LIMIT
تتيح لك عبارة LIMIT
تحديد عدد النتائج التي سيتم عرضها.
ويكون هذا مفيدًا إذا كنت مهتمًا فقط بالملخص.
على سبيل المثال، يمكن استخدام LIMIT
لتقييد إجمالي عدد نتائج
الاستعلام التالي:
SELECT
campaign.name,
ad_group.name,
segments.device,
metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50
المعلمات
تتيح لك العبارة PARAMETERS
تحديد معلَمات وصفية للطلب.
قد تؤثر هذه المعلمات في أنواع الصفوف التي يتم عرضها.
في الوقت الحالي، يمكن استخدام المعلمات الوصفية التالية:
include_drafts
اضبط include_drafts
على true
للسماح بعرض مسودّات الكيانات.
وتكون القيمة التلقائية هي false
.
على سبيل المثال، يجلب طلب البحث التالي الحملات الاختبارية إلى جانب الحملات العادية الحملات:
SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true
omit_unselected_resource_names
اضبط omit_unselected_resource_names
على true
لمنع اسم المورد
عرض كل نوع من أنواع الموارد في الاستجابة ما لم يتم طلبه صراحةً
في عبارة SELECT
. وتكون القيمة التلقائية هي false
.
أمثلة على omit_unselected_resource_names | |
---|---|
SELECT campaign.name, customer.id FROM campaign |
Returned resources: campaign.resource_name
يتم ضبط omit_unselected_resource_names تلقائيًا على false ، وبالتالي
سيتم إرجاع جميع حقول resources_name.
|
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true |
Returned resources: ما مِن إجراءات مقترَحة. تم تحديد omit_unselected_resource_names على أنّه true
وcampaign.resource_name وcustomer.resource_name
ليست جزءًا من عبارة SELECT .
|
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true |
Returned resource: campaign.resource_name
تم تحديد omit_unselected_resource_names على أنّه true
وطلب campaign.resource_name كجزء من
SELECT .
|
قواعد اللغة الإضافية
بالإضافة إلى أمثلة كل عبارة، تحتوي لغة طلب البحث في "إعلانات Google" على ما يلي السلوكيات التي يمكن استخدامها:
ليس من الضروري أن يكون حقل المورد الرئيسي في
SELECT
. لطلب بحث ما. على سبيل المثال، قد تحتاج إلى استخدام عنصر رئيسي واحد أو أكثر حقول الموارد لتصفية البيانات:SELECT campaign.id FROM ad_group WHERE ad_group.status = PAUSED
يمكن اختيار المقاييس بشكل حصري لمورد معيّن. ما مِن حقول أخرى من المورد مطلوبة في الاستعلام:
SELECT metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign
يمكن اختيار حقول التقسيم بدون أي حقول موارد مرفقة أو المقاييس:
SELECT segments.device FROM campaign
يمكن إدخال الحقل
resource_name
(مثلاً،campaign.resource_name
) يُستخدم لتصفية البيانات أو ترتيبها:SELECT campaign.id, campaign.name FROM campaign WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'