لغة طلب البحث في "إعلانات Google"

يمكن للغة طلب البحث في "إعلانات Google" تنفيذ طلب بحث في Google Ads API

الموارد والسمات والشرائح والمقاييس ذات الصلة باستخدام
GoogleAdsService بحث Google أو SearchStream
النتيجة من طلب بحث GoogleAdsService هي قائمة تتضمّن GoogleAdsRow مثيلات، ويمثل كل GoogleAdsRow موردًا. إذا تم طلب أي سمات أو مقاييس، فإن الصف سيتضمن أيضًا هذه الحقول. إذا تم طلب أي شرائح، ستعرض الاستجابة أيضًا صفًا إضافيًا لكل صف من صفوف موارد الشريحة.
بيانات التعريف حول الحقول والموارد المتاحة في
GoogleAdsFieldService

توفر هذه الخدمة كتالوجًا من الحقول التي يمكن الاستعلام عنها مع تفاصيل حول توافقها ونوعها.

نتيجة طلب البحث GoogleAdsFieldService هي قائمة تتضمّن GoogleAdsField مثيلات، يحتوي كل GoogleAdsField على تفاصيل حول الحقل المطلوب.

الاستعلام عن سمات مورد

في ما يلي طلب بحث أساسي لسمات مورد الحملة، مع توضيح كيفية عرض رقم تعريف الحملة واسمها وحالتها:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

يتم ترتيب هذا الطلب حسب رقم تعريف الحملة. وستمثل كل GoogleAdsRow نتيجة عنصر campaign تمت تعبئته بالحقول المحددة (بما في ذلك resource_name للحملة المحددة).

لمعرفة الحقول الأخرى المتاحة لطلبات البحث الخاصة بالحملة، يُرجى الاطّلاع على المستندات المرجعية الخاصة بـ Campaign.

الاستعلام عن مقاييس

إلى جانب السمات المحدّدة لمورد معيّن، يمكنك أيضًا طلب البحث عن المقاييس ذات الصلة:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

يؤدي طلب البحث هذا إلى فلترة الحملات بالحالة "PAUSED" والتي سجّلت أكثر من 1, 000 مرّة ظهور، في حين يتمّ ترتيبها حسب رقم تعريف الحملة. وكل GoogleAdsRow نتيجة لذلك سيكون لها حقل metrics تمت تعبئته بالمقاييس المحدّدة.

للحصول على قائمة بالمقاييس التي يمكن طلبها، يُرجى الاطّلاع على Metrics الوثائق.

الاستعلام عن الشرائح

إلى جانب السمات المحددة لمورد معيّن، يمكنك أيضًا الاستعلام عن المقاطع ذات الصلة:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date,
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date during LAST_30_DAYS
ORDER BY campaign.id

وعلى غرار طلبات البحث عن المقاييس، لا تتم فلترة طلب البحث هذا إلا للحملات التي تحمل الحالة PAUSED والتي حقّقت أكثر من 1,000 مرة ظهور. ومع ذلك، يعمل طلب البحث هذا على تقسيم البيانات حسب التاريخ. ويؤدي ذلك إلى أن تكون كل قيمة GoogleAdsRow نتيجة تمثل صفًا من إحدى الحملات وتاريخ Segment. من المهم ملاحظة أن التقسيم يؤدي إلى تقسيم المقاييس المحددة، وتجميعها حسب كل شريحة في عبارة SELECT.

للحصول على قائمة بالمقاطع التي يمكن طلب البحث فيها، راجِع Segments المستندات.

في استعلام لمورد معين، قد تتمكن من الانضمام إلى الموارد الأخرى ذات الصلة إذا كان ذلك متاحًا. تُعرف هذه الموارد ذات الصلة باسم "الموارد المنسوبة". يمكنك الانضمام إلى الموارد المنسوبة ضمنيًا عن طريق اختيار سمة في طلب بحثك.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

لا يحدد طلب البحث هذا سمات الحملة فقط، بل يسحب أيضًا السمات ذات الصلة من كل حملة محددة. تمثّل كل سمة GoogleAdsRow نتيجة عنصر campaign تمت تعبئته بسمات الحملة المحدّدة وسمة استراتيجية عروض الأسعار المحدّدة bidding_strategy.name.

لمعرفة الموارد المنسوبة المتاحة لطلبات البحث المتعلقة بالحملة، يمكنك الاطّلاع على المستندات المرجعية لـ Campaign.

التغيير بناءً على نتائج طلب البحث

عند الاستعلام عن مورد معين، يمكنك على الفور أخذ هذه النتائج التي تم إرجاعها ككائنات، وتعديلها، وإرسالها مرة أخرى إلى طريقة التبديل في خدمة هذا المورد. في ما يلي نموذج لسير العمل:

  1. نفِّذ طلب بحث لجميع الحملات التي يبلغ سعرها حاليًا PAUSED والتي تحتوي على مرّات ظهور أكبر من 1,000.
  2. احصل على الكائن Campaign من الحقل campaign لكل GoogleAdsRow في الرد.
  3. غيِّر حالة كل حملة من PAUSED إلى ENABLED.
  4. اتصل بـ CampaignService.MutateCampaigns مع الحملات المعدَّلة لتعديلها.

البيانات الوصفية للحقل

إنّ طلبات البحث التي يتم إرسالها إلى GoogleAdsFieldService تهدف إلى استرداد البيانات الوصفية للحقل. يمكن استخدام هذه المعلومات لفهم كيفية استخدام الحقول معًا في الاستعلام. وبما أنّ البيانات متوفرة من واجهة برمجة التطبيقات وتوفر البيانات الوصفية اللازمة اللازمة للتحقّق من صحة طلب البحث أو إنشائه، يتيح ذلك للمطوّرين إجراء ذلك بشكل آلي. إليك استعلام نموذجي لبيانات التعريف:

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

يمكنك استبدال <INSERT_RESOURCE_OR_FIELD> في طلب البحث هذا إما بمورد (مثل customer أو campaign) أو حقل (مثل campaign.id أو metrics.impressions أو ad_group.id).

للحصول على قائمة بالحقول التي يمكن طلبها، يُرجى الاطّلاع على المستندات GoogleAdsField.

أمثلة على التعليمات البرمجية

تتضمّن مكتبات العملاء أمثلة على استخدام لغة طلب البحث في "إعلانات Google" في GoogleAdsService. ويحتوي مجلد العمليات الأساسية على أمثلة مثل GetCampaigns وGetKeywords وSearchForGoogleAdsFields. يتضمن مجلد Reporting مثالاً على GetKeywordStats.