تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

المصطلحات الأساسية

المورد: كيان في "إعلانات Google"، مثل campaign أو ad_group
تقسيم: سمة مستخدَمة لتجميع البيانات، مثل segments.date أو segments.device عند تضمين شرائح في عبارة SELECT مع مقاييس، يتم تقسيم المقاييس حسب الشريحة.
المقياس: مقياس للأداء، مثل metrics.impressions أو metrics.clicks
مرجع منسوب: مورد يتم ربطه ضمنيًا بالمورد الرئيسي في عبارة FROM ، ما يتيح لك اختيار سماته مع سمات المورد الرئيسي.

طلب البحث عن معلومات الموارد أو البيانات الوصفية

يمكن أن تستعلم "لغة طلبات البحث في إعلانات Google" عن Google Ads API للحصول على أنواع المعلومات التالية:

الموارد وسماتها وشرائحها ومقاييسها ذات الصلة باستخدام GoogleAdsService Search أو SearchStream: نتيجة طلب البحث GoogleAdsService هي قائمة بمثيلات GoogleAdsRow، ويمثّل كل GoogleAdsRow موردًا.

إذا تم طلب أي سمات أو مقاييس، سيتضمّن الصف أيضًا هذه الحقول. في حال طلب أي شرائح، سيعرض الرد أيضًا صفًا إضافيًا لكل مجموعة من شريحة ومورد.
البيانات الوصفية حول الحقول والموارد المتاحة في GoogleAdsFieldService: توفّر هذه الخدمة قائمة بالحقول التي يمكن البحث فيها مع تفاصيل حول توافقها ونوعها.

نتيجة طلب البحث GoogleAdsFieldService هي قائمة بمثيلات GoogleAdsField، ويتضمّن كل GoogleAdsField تفاصيل حول الحقل المطلوب.

لمزيد من التفاصيل حول بنية طلب البحث، اطّلِع على بنية طلب البحث وقواعد "لغة طلبات البحث في إعلانات Google".

طلب سمات الموارد

في ما يلي مثال على طلب بحث أساسي عن سمات مورد الحملة يوضّح كيفية عرض رقم تعريف الحملة واسمها وحالتها:

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 ناتج يمثّل مجموعة من الحملة والشريحة الزمنية. يؤدي التقسيم إلى فصل المقاييس المحدّدة، مع تجميعها حسب كل قسم في عبارة SELECT.

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

في طلب بحث عن مورد معيّن، قد تتمكّن من الربط بموارد أخرى ذات صلة إذا كانت متاحة. تُعرف المراجع ذات الصلة هذه باسم "المراجع المنسوبة". يمكنك الربط بموارد ذات سمات بشكل ضِمني من خلال اختيار سمة في طلب البحث.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

لا يختار طلب البحث هذا سمات الحملة فحسب، بل يجلب أيضًا السمات ذات الصلة من كل حملة تم اختيارها. يمثّل كل GoogleAdsRow ناتج كائن campaign مملوء بسمات الحملة المحدّدة، بالإضافة إلى سمة استراتيجية عروض الأسعار المحدّدة bidding_strategy.name.

لمعرفة الموارد المنسوبة المتاحة لطلبات البحث عن الحملات، يُرجى الرجوع إلى المستندات المرجعية Campaign.

أفضل الممارسات

اختَر الحقول التي تحتاج إليها فقط لتجنُّب أوقات الاستجابة الطويلة والمهلة الزمنية.
استخدِم LIMIT أثناء التطوير والاختبار لتجنُّب معالجة مجموعات كبيرة من النتائج.
طبِّق الفلاتر في البند البرمجي WHERE لتقليل حجم نقل البيانات والاستجابة.
استخدِم GoogleAdsFieldService للتحقّق من توافق الحقول وأنواع البيانات قبل إنشاء طلبات بحث معقّدة.
يُرجى العِلم أنّ بعض الحقول، خاصةً تلك التي تتضمّن كميات كبيرة من البيانات أو عمليات حسابية معقّدة، يمكن أن تزيد من تكلفة طلب البحث.

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

عند طلب البحث عن مورد معيّن، يمكنك على الفور اعتبار النتائج التي تم عرضها كعناصر وتعديلها وإعادة إرسالها إلى طريقة التعديل في خدمة هذا المورد. في ما يلي مثال على سير العمل:

نفِّذ طلب بحث عن جميع الحملات PAUSED التي سجّلت مرّات ظهور أكبر من 1,000.
احصل على الكائن Campaign من الحقل campaign لكل GoogleAdsRow في الردّ.
غيِّر حالة كل حملة من PAUSED إلى ENABLED.
اتّصِل بالرقم CampaignService.MutateCampaigns مع الحملات المعدَّلة وFieldMask مطابق لتعديلها.

البيانات الوصفية للحقل

تهدف الطلبات المُرسَلة إلى 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 Ads Query Language وبنودها وعوامل تشغيلها متطابقة في جميع إصدارات Google Ads API المتوافقة (الإصدار 23 والإصدار 24 والإصدار 25)، يختلف دليل الموارد القابلة للاستعلام والشرائح والمقاييس وسلوك إعداد التقارير حسب رقم الإصدار الرئيسي. يمكنك إرسال طلب بحث إلى GoogleAdsFieldService عند نقطة نهاية إصدار واجهة برمجة التطبيقات المستهدَف لفحص الحقول وقواعد التوافق لهذا الإصدار:

مراجع أهداف مراحل النشاط: في الإصدار 25 والإصدارات الأحدث، يتم طلب جميع أهداف مراحل النشاط (اكتساب عملاء جدد والاحتفاظ بالعملاء والاحتفاظ بالعملاء الأوفياء) من المرجعَين الموحّدَين goal وcampaign_goal_config، ما يحلّ محلّ customer_lifecycle_goal وcampaign_lifecycle_goal (اللذين كانا يُستخدمان لأهداف اكتساب عملاء جدد في الإصدار 24 والإصدارات الأقدم، إلى جانب goal وcampaign_goal_config لأهداف الاحتفاظ بالعملاء).
مقاييس عرض مواد عرض توسيع عنوان URL النهائي: في الإصدار 25 والإصدارات الأحدث، يؤدي طلب البحث عن final_url_expansion_asset_view إلى عرض جميع المقاييس القابلة للتحديد للعرض. في الإصدار 24 والإصدارات الأقدم، تتضمّن الردود metrics.conversions وmetrics.conversions_value فقط لـ "حملات الأداء الأفضل" وmetrics.impressions لـ "الحملات على شبكة البحث".
تتبُّع أداء المنتج في "حملات التطبيقات": في الإصدار 24 والإصدارات الأحدث، يعرض مورد shopping_product صفوف المنتجات في "حملات التطبيقات" بالإضافة إلى "حملات Shopping" و"حملات الأداء الأفضل" و"حملات زيادة الطلب" و"حملات الفيديو" (في الإصدار 23، يتم استبعاد "حملات التطبيقات" من نتائج shopping_product).
المَراجع والأقسام والمقاييس الخاصة بالإصدار:
- الإصدار 25 والإصدارات الأحدث: يتضمّن هذا الإصدار مراجع لقياس التحسّن (مثل lift_measurement_config) وشرائح مثل segments.ad_sub_format_type وsegments.loyalty_membership ومقاييس التفاعل على YouTube (metrics.youtube_likes وmetrics.youtube_comments وmetrics.youtube_shares). تتم إزالة local_services_lead.contact_details.email (التي يمكن اختيارها في الإصدار 24 والإصدارات الأقدم).
- الإصدار 24 والإصدارات الأحدث: يتضمّن المورد cart_data_sales_view وsegments.conversion_attribution_event_type على shopping_performance_view وsegments.mobile_device_platform وsegments.ad_network_type على performance_max_placement_view. تتم إزالة campaign.video_brand_safety_suitability (يتم استبدالها بـ customer.video_brand_safety_suitability) وsegments.ad_sub_network_type على campaign_budget وsegments.click_type على ad_group_asset وcampaign_asset وcustomer_asset (التي يمكن تحديدها فقط في الإصدار 23).
رمز الخطأ في البحث عن البيانات الدقيقة في الماضي: إنّ طلبات البحث التي يتم تقسيمها حسب segments.date أو segments.week أو segments.hour (أو التي يتم فلترتها حسب نطاق زمني أقل من شهر واحد) بعد فترة معاينة الإعلان البالغة 37 شهرًا تعرض الخطأ DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED في الإصدار 24 والإصدارات الأحدث (أو DateRangeError.UNKNOWN في الإصدار 23). يمكنك الاطّلاع على النطاقات الزمنية لمعرفة التفاصيل.

أمثلة على الرموز البرمجية

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

قواعد طلب البحث