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

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

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

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

البنود

ondemand_video فيديو: توافق حقل GAQL

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.

SELECT
  campaign.name,
  customer.id
FROM campaign

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

قواعد اللغة الإضافية

بالإضافة إلى أمثلة كل عبارة، تحتوي لغة طلب البحث في "إعلانات 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'