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

يمكن إرسال طلبات البحث عن حقول الموارد والشرائح والمقاييس إلى GoogleAdsService طريقتَي Search أو SearchStream. لإنشاء طلب بحث بلغة طلبات البحث في "إعلانات Google"، عليك إنشاؤه باستخدام قواعد اللغة. يتألّف طلب البحث من عدد من الجُمل:

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT
• PARAMETERS

تستخدِم الجمل أسماء الحقول وأسماء الموارد والمشغِّلات والشروط و عمليات الترتيب لمساعدتك في اختيار البيانات الصحيحة. وبعد دمجها في طلب بحث واحد، يمكن تقديم طلب باستخدام Google Ads API.

نقطة رئيسية: يوفّر GoogleAdsFieldService كتالوجًا لعملاء لغة طلبات البحث في "إعلانات Google" يتضمّن بيانات وصفية عن جميع حقول موارد الحقول وشرائح الجمهور والمقاييس، بالإضافة إلى علاقاتهم ببعضها البعض ومدى توفّرها في كلّ عبارة على النحو الموضّح أدناه. لمزيد من التفاصيل، يُرجى الرجوع إلى مستندات GoogleAdsField.

العبارات

فيديو: التوافق مع حقول لغة الاستعلامات في "إحصاءات Google"

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، وذلك بسبب القيود التالية:

• طلب البحث في حقول غير قابلة للاختيار ستتم الإشارة إلى سمة البيانات الوصفية Selectable في هذه الحقول بعلامة false.
• اختيار سمات الحقول المتكرّرة ستتم الإشارة إلى سمة البيانات الوصفية isRepeated في هذه الحقول بعلامة true.
• اختيار حقول غير متاحة للمورد المحدّد في عبارة FROM لا يمكن اختيار سمات بعض الموارد معًا، ولن تتوفّر سوى مجموعة فرعية من جميع المقاييس والشرائح للمورد في عبارة FROM.
• اختيار شرائح أو مقاييس غير متوافقة مع بعضها للحصول على مزيد من المعلومات حول هذا الموضوع، يُرجى الاطّلاع على قسم التصنيف إلى شرائح.

يمكن العثور على معلومات متعلّقة بالشروط المذكورة أعلاه في مستندات المرجع أو من GoogleAdsFieldService.

FROM

تحدّد العبارة FROM المورد الرئيسي الذي سيتم إرجاعه. يحدِّد المورد في العبارة FROM الحقول التي يمكن استخدامها في كل العبارة الأخرى لطلب البحث المحدّد. يمكن تحديد مورد واحد فقط في عبارة FROM. تكون عبارة FROM مطلوبة في طلب موجَّه إلى أسلوبَي GoogleAdsService Search أو 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

ملاحظة مهمة: إذا كان المورد في عبارة FROM يسرد موردًا آخر على أنّه segment، سيؤدي اختيار أيّ سمات من هذا المورد إلى التصرّف كقسم.

أين؟

تحدِّد عبارة 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 وsegments.week وsegments.month وsegments.quarter وsegments.year. في حال اختيار أيٍّ من هذه الشرائح، يجب استخدام واحد منها على الأقل في عبارة WHERE.

نقطة رئيسية: لا يمكن استخدام الفاصل AND إلا بين شروط عوامل التشغيل (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE")، وليس داخل شرط عامل تشغيل واحد (WHERE segments.device != "DESKTOP" AND "MOBILE").

عند الفلترة، من المهم مراعاة حساسية عامل التشغيل لحالة الأحرف. اطّلِع على الحساسية لحالة الأحرف لمزيد من التفاصيل.

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

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

النقطة الرئيسية: يتيح لك الرمز LIMIT اقتطاع النتائج. استخدِم حقل page_size في GoogleAdsService.Search لمعالجة قوائم طويلة من النتائج.

المَعلمات

تسمح لك العبارة 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.

ملاحظة: إذا كنت تخطّط لاستخدام أيّ من العناصر المعروضة لإجراء عمليات تعديل أو إزالة، ننصحك بضبط هذا الخيار على false لأنّه لا يمكن استخدام موارد بدون أسماء موارد في عمليات التعديل. في حال ضبط هذا الخيار على true، تأكَّد من طلب أسماء الموارد صراحةً لكلٍّ من المورد الأساسي وأيّ موارد سمات تحصل عليها باستخدام الطلب.

أمثلة على omit_unselected_resource_names
SELECT campaign.name, customer.id FROM campaign	Returned resources: campaign.resource_name customer.resource_name القيمة التلقائية لسمة omit_unselected_resource_names هي false، لذا يتم عرض جميع حقول resource_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'