لغة طلب البحث في "إعلانات 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. 1. احصل على الكائن Campaign من الحقل campaign لكل GoogleAdsRow في الرد. 1. غيِّر حالة كل حملة من PAUSED إلى ENABLED. 1. اتّصِل بالرقم 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).

نقطة أساسية: يُرجى العِلم أنّه لا توجد عبارة FROM في هذا الاستعلام.

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

أمثلة على الرموز

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