يمكن للغة طلب البحث في "إعلانات Google" تنفيذ طلب بحث في Google Ads API
- الموارد والسمات والشرائح والمقاييس ذات الصلة باستخدام
GoogleAdsService
بحث Google أو 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
.
التغيير بناءً على نتائج طلب البحث
عند الاستعلام عن مورد معين، يمكنك على الفور أخذ هذه النتائج التي تم إرجاعها ككائنات، وتعديلها، وإرسالها مرة أخرى إلى طريقة التبديل في خدمة هذا المورد. في ما يلي نموذج لسير العمل:
- نفِّذ طلب بحث لجميع الحملات التي يبلغ سعرها حاليًا
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
.
يتضمن مجلد Reporting مثالاً على GetKeywordStats
.