يمكن للغة طلب البحث في إعلانات 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 في خدمة هذا المورد. في ما يلي نموذج لسير العمل:
- نفِّذ طلب بحث لجميع الحملات التي تمثّل
PAUSED
حاليًا والتي يبلغ عدد مرات ظهورها أكثر من 1,000. - احصل على كائن
Campaign
من الحقلcampaign
لكلGoogleAdsRow
في الردّ. - غيِّر حالة كلّ حملة من
PAUSED
إلىENABLED
. - يمكنك الاتصال بالرقم
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
.