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

ملاحظة: استخدِم أداة إنشاء طلبات البحث التفاعلية لإنشاء طلبات بحث GAQL والتحقّق من صحتها.

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

المورد

كيان في "إعلانات 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 للتحقّق من توافق الحقول وأنواع البيانات قبل إنشاء طلبات بحث معقّدة.
• يُرجى العِلم أنّ بعض الحقول، خاصةً تلك التي تتضمّن كميات كبيرة من البيانات أو عمليات حسابية معقّدة، يمكن أن تزيد من تكلفة طلب البحث.

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

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

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

ملاحظة: عند تعديل الموارد التي تم استردادها من طلب بحث، حدِّد FieldMask (أو استخدِم أداة قناع الحقل المضمّنة في مكتبة البرامج) بحيث يتم تعديل الحقول المعدَّلة فقط، لتجنُّب أخطاء READ_ONLY_FIELD أو IMMUTABLE_FIELD، أو استبدال سمات أخرى عن غير قصد.

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

إنّ طلبات البحث المرسَلة إلى 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).

نقطة أساسية: يُرجى العِلم أنّه لا يوجد عبارة FROM في هذا الطلب.

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

الاختلافات الخاصة بالإصدارات

على الرغم من أنّ بنية لغة طلب البحث في "إعلانات Google" وبنودها وعوامل تشغيلها متطابقة في جميع إصدارات Google Ads API المتوافقة (الإصدارات 23 و24 و25 و26)، يختلف كتالوج الموارد القابلة لطلب البحث والشرائح والمقاييس وسلوكيات إعداد التقارير حسب رقم الإصدار الرئيسي. يمكنك إرسال طلب بحث إلى GoogleAdsFieldService في نقطة نهاية إصدار واجهة برمجة التطبيقات المستهدَف لفحص الحقول وقواعد التوافق لهذا الإصدار:

• طريقة عرض مواد عرض "توسيع عنوان URL النهائي":
  • إتاحة "حملات تسوّق" (الإصدار 26 والإصدارات الأحدث): يتيح final_url_expansion_asset_view استخدام "حملات تسوّق" (campaign.advertising_channel_type = 'SHOPPING') بالإضافة إلى "حملات الأداء الأفضل" و"الحملات على شبكة البحث". بالنسبة إلى حملات التسوّق، يمكنك اختيار حقول ad_group والفلترة حسبها، ولكن لا يمكنك اختيار حقول asset_group.
  • المقاييس القابلة للاختيار (الإصدار 25 والإصدارات الأحدث): يؤدي الاستعلام عن final_url_expansion_asset_view إلى عرض جميع المقاييس القابلة للاختيار في طريقة العرض. في الإصدار 24 والإصدارات الأقدم، تتضمّن الردود فقط metrics.conversions وmetrics.conversions_value لـ "حملات الأداء الأفضل" وmetrics.impressions لـ "الحملات على شبكة البحث".
• موارد أهداف مراحل النشاط: في الإصدار 25 والإصدارات الأحدث، يتم الاستعلام عن جميع أهداف مراحل النشاط (اكتساب العملاء الجدد والاحتفاظ بالعملاء والاحتفاظ بالعملاء الأوفياء) من الموردَين الموحّدَين goal وcampaign_goal_config، ما يحلّ محلّ customer_lifecycle_goal وcampaign_lifecycle_goal (اللذين تم استخدامهما لأهداف اكتساب العملاء الجدد في الإصدار 24 والإصدارات الأقدم، إلى جانب goal وcampaign_goal_config لأهداف الاحتفاظ بالعملاء).
• تتبُّع أداء المنتج في "حملات التطبيقات": في الإصدار 24 والإصدارات الأحدث، يعرض المورد shopping_product صفوف المنتجات في "حملات التطبيقات" بالإضافة إلى "حملات Shopping" و"حملات الأداء الأفضل" و"حملات زيادة الطلب" و"حملات الفيديو" (في الإصدار 23، يتم استبعاد "حملات التطبيقات" من نتائج shopping_product).
• الموارد والأقسام والمقاييس الخاصة بالإصدار:
  • الإصدار 26 والإصدارات الأحدث: يتضمّن المورد search_lift_keyword_bundle، وcampaign.lift_measurement_config وlocal_services_lead.campaign وsegments.search_lift_keyword_bundle وsegments.search_property ومقاييس "زيادة البحث" (مثل metrics.relative_search_lift وmetrics.normalized_incremental_searches وmetrics.search_lift_cost_micros وmetrics.search_lift_impressions).
  • الإصدار 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.