يمكن إرسال طلبات البحث عن حقول الموارد والشرائح والمقاييس إلى طريقة
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
مطلوبة في طلب البحث إلى طريقة
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
جميع الشرائح التي تستوفي الشرط أعلاه هي: segment.date، وsegment.week،
وsegments.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
لتقييد العدد الإجمالي للنتائج لطلب البحث التالي:
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 ، لذلك
يتم عرض جميع حقول provider_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'