البيانات الوصفية للمرجع

يمكنك استخدام GoogleAdsFieldService (من خلال GetGoogleAdsField أو SearchGoogleAdsFields) لطلب كتالوج الموارد وحقول الموارد ومفاتيح التقسيم والمقاييس المتاحة في الطريقتَين GoogleAdsService Search وSearchStream بشكل ديناميكي. يوفّر الفهرس بيانات وصفية يمكن أن يستخدمها عملاء Google Ads API للتحقّق من صحة عبارات "لغة طلب البحث في إعلانات Google" وإنشائها.

نموذج لطلب واستجابة HTTP

يتألف الطلب من HTTP GET إلى خادم Google Ads API على عنوان URL التالي:

https://googleads.googleapis.com/v25/googleAdsFields/{resource_or_field}

يعرض المثال التالي طلبًا متبوعًا بالرد الذي تم تلقّيه من GoogleAdsFieldService للمورد ad_group:

طلب

https://googleads.googleapis.com/v25/googleAdsFields/ad_group

الردّ

{
  "resourceName": "googleAdsFields/ad_group",
  "name": "ad_group",
  "category": "RESOURCE",
  "selectable": false,
  "filterable": false,
  "sortable": false,
  "selectableWith": [
    "campaign",
    "customer",
    "metrics.average_cpc",
    "segments.device"
  ],
  "attributeResources": [
    "customer",
    "campaign"
  ],
  "metrics": [
    "metrics.conversions",
    "metrics.search_budget_lost_impression_share",
    "metrics.average_cost",
    "metrics.clicks"
  ],
  "segments": [
    "segments.date",
    "segments.ad_network_type",
    "segments.device"
  ]
}

في هذا المثال، الصفائف المهمة هي:

attributeResources

الموارد التي يمكن ربطها ضمنيًا بالمرجع في عبارة FROM بدون تقسيم المقاييس. تتم تعبئة هذا الحقل فقط للحقول التي تكون فيها قيمة category هي RESOURCE.

metrics

المقاييس التي يمكن تحديدها باستخدام المرجع في عبارة FROM. تتم تعبئة هذا الحقل فقط للحقول التي تكون فيها قيمة category هي RESOURCE.

segments

مفاتيح التقسيم (حقول segments.* وموارد التقسيم) التي يمكن اختيارها مع المورد في عبارة FROM وتقسّم هذه السمة المقاييس المحدّدة في طلب البحث. تتم تعبئة هذا الحقل فقط للحقول التي تكون فيها قيمة category هي RESOURCE.

selectableWith

الموارد أو الشرائح أو المقاييس التي يمكن اختيارها في طلب بحث واحد بلغة طلبات البحث في "إعلانات Google" عندما لا يكون هذا المورد أو هذه الشريحة هي المورد الأساسي في عبارة FROM

طلب التوافق مع selectableWith

تحدّد السمة selectableWith في حقل مورد أو شريحة موارد أو شرائح أو مقاييس أخرى يمكن اختيارها في طلب بحث واحد بلغة طلبات البحث في "إعلانات Google". تكون هذه السمة ضرورية عندما تريد تضمين حقول من مصدر أو شريحة غير محدّدة في عبارة FROM.

عند إنشاء طلب بحث بلغة طلبات البحث في "إعلانات Google"، اتّبِع الخطوات التالية:

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

تحتوي قائمة selectableWith لمصدر معيّن (المصدر "أ") على جميع المصادر والأقسام والمقاييس الأخرى التي يمكن اختيارها إلى جانب الحقول من المصدر "أ" عندما لا يكون المصدر "أ" هو العنصر الأساسي.

مثال

ضع في اعتبارك مثال طلب البحث التالي:

SELECT ad_group.id, segments.date, campaign.name FROM ad_group

• تحدّد عبارة FROM ad_group.
• يختار هذا الاستعلام ad_group.id (من المورد FROM) وsegments.date وcampaign.name.
• بما أنّ campaign.name محدّد، ولكن campaign ليس في بند برمجي FROM، عليك التحقّق من توافقه مع العناصر الأخرى المحدّدة.
• لضمان صحة طلب البحث هذا، يجب أن يكون المرجع campaign متوافقًا مع segments.date (حقل آخر يتم اختياره). لذلك، عليك التحقّق من السمة selectableWith للمرجع campaign. إذا كانت السمة segments.date متوفّرة في قائمة selectableWith الخاصة بـ campaign، يكون طلب البحث صالحًا.

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

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

يمكنك طلب الكتالوج باستخدام GoogleAdsFieldService (إما حسب اسم المورد مع GetGoogleAdsField أو عن طريق طلب البحث باستخدام SearchGoogleAdsFields) على مستويات GoogleAdsFieldCategory التالية:

المورد (RESOURCE)

على سبيل المثال، googleAdsFields/campaign.

سمة المرجع (ATTRIBUTE)

على سبيل المثال، googleAdsFields/campaign.name.

حقل التقسيم (SEGMENT)

على سبيل المثال، googleAdsFields/segments.ad_network_type.

المقياس (METRIC)

على سبيل المثال، googleAdsFields/metrics.clicks.