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

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

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

GoogleAdsService بحث أو 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 المرجعية.

التبديل استنادًا إلى نتائج طلب البحث

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

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. يحتوي مجلد إعداد التقارير على مثال GetKeywordStats.