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

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

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

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

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

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

طلب

https://googleads.googleapis.com/v22/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.

metrics

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

segments

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

selectableWith

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

عند إنشاء طلب بحث GAQL، يجب مراعاة ما يلي:

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 على المستويات التالية:

المورد

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

حقل المرجع

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

حقل التقسيم

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

المقياس

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