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

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

الموارد والسمات والشرائح والمقاييس ذات الصلة باستخدام

GoogleAdsService Search أو 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.