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

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

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

GoogleAdsService البحث أو SearchStream

النتيجة من طلب بحث في "إعلانات Google" هي قائمة من أمثلة 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 فقط، والتي سجّلت أكثر من 1000 مرة ظهور، مع ترتيبها حسب رقم تعريف الحملة. سيؤدي ملء 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 والتي سجّلت أكثر من 1000 مرة ظهور. ومع ذلك، يعمل طلب البحث هذا على تقسيم البيانات حسب التاريخ. ويؤدي ذلك إلى أن تمثّل كل نتيجة 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 والتي حققت مرات ظهور أكبر من 1000.
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. يحتوي مجلد إعداد التقارير على مثال GetKeywordStats.