كتاب الطبخ الخاص بطلب البحث

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

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

ملاحظة رئيسية: توضّح علامات التبويب cURL أدناه استخدام واجهة RST في واجهة برمجة التطبيقات مباشرةً. يمكنك الاطّلاع على صفحة search الخاصة بدليل REST لمعرفة المزيد من التفاصيل.

نسخ شاشات واجهة المستخدم في "إعلانات Google"

يعرض هذا القسم طلبات بحث واجهة برمجة التطبيقات التي تعرض البيانات نفسها التي تعرِضها الشاشات التلقائية لواجهة مستخدم "إعلانات Google". إذا كنت تنشئ تطبيقًا يعرض مقاييس وبيانات مشابهة لـ "إعلانات Google"، يمكن أن تساعدك طلبات البحث هذه في سحب بيانات مماثلة من واجهة برمجة التطبيقات.

ملاحظة: ما لم يُنصّ على خلاف ذلك، يتم تلقائيًا عرض بيانات من آخر سبعة أيام في جميع طلبات البحث المؤرخة في هذا الدليل.

الحملات

شاشة "نظرة عامة على الحملات" التلقائية في واجهة المستخدِم

شاشة واجهة المستخدم

طلب بحث واجهة برمجة التطبيقات

مورّد Google Analytics

SELECT campaign.name,
  campaign_budget.amount_micros,
  campaign.status,
  campaign.optimization_score,
  campaign.advertising_channel_type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.bidding_strategy_type
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status != 'REMOVED'

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT campaign.name,
    campaign_budget.amount_micros,
    campaign.status,
    campaign.optimization_score,
    campaign.advertising_channel_type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.bidding_strategy_type
  FROM campaign
  WHERE segments.date DURING LAST_7_DAYS
    AND campaign.status != 'REMOVED'
"
}'

المجموعات الإعلانية

شاشة نظرة عامة على المجموعات الإعلانية التلقائية في واجهة المستخدِم

شاشة واجهة المستخدم

طلب بحث واجهة برمجة التطبيقات

مورّد Google Analytics

SELECT ad_group.name,
  campaign.name,
  ad_group.status,
  ad_group.type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM ad_group
WHERE segments.date DURING LAST_7_DAYS
  AND ad_group.status != 'REMOVED'

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT ad_group.name,
    campaign.name,
    ad_group.status,
    ad_group.type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros
  FROM ad_group
  WHERE segments.date DURING LAST_7_DAYS
    AND ad_group.status != 'REMOVED'
"
}'

الإعلانات

شاشة النظرة العامة التلقائية على "إعلانات Google" في واجهة المستخدم

تجدر الإشارة إلى أنّ طلب البحث هذا يجلب على وجه التحديد المكوّنات الفردية لإعلان نصي موسَّع، والتي تظهر معًا في عمود الإعلان على شاشة واجهة المستخدم.

شاشة واجهة المستخدم

طلب بحث واجهة برمجة التطبيقات

مورّد Google Analytics

SELECT ad_group_ad.ad.expanded_text_ad.headline_part1,
  ad_group_ad.ad.expanded_text_ad.headline_part2,
  ad_group_ad.ad.expanded_text_ad.headline_part3,
  ad_group_ad.ad.final_urls,
  ad_group_ad.ad.expanded_text_ad.description,
  ad_group_ad.ad.expanded_text_ad.description2,
  campaign.name,
  ad_group.name,
  ad_group_ad.policy_summary.approval_status,
  ad_group_ad.ad.type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM ad_group_ad
WHERE segments.date DURING LAST_7_DAYS
  AND ad_group_ad.status != 'REMOVED'

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT ad_group_ad.ad.expanded_text_ad.headline_part1,
    ad_group_ad.ad.expanded_text_ad.headline_part2,
    ad_group_ad.ad.expanded_text_ad.headline_part3,
    ad_group_ad.ad.final_urls,
    ad_group_ad.ad.expanded_text_ad.description,
    ad_group_ad.ad.expanded_text_ad.description2,
    campaign.name,
    ad_group.name,
    ad_group_ad.policy_summary.approval_status,
    ad_group_ad.ad.type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros
  FROM ad_group_ad
  WHERE segments.date DURING LAST_7_DAYS
    AND ad_group_ad.status != 'REMOVED'
"
}'

البحث عن الكلمات الرئيسية

شاشة نظرة عامة على الكلمات الرئيسية للإعلان على شبكة البحث التلقائية في واجهة المستخدم

شاشة واجهة المستخدم

طلب بحث واجهة برمجة التطبيقات

مورّد Google Analytics

SELECT ad_group_criterion.keyword.text,
  campaign.name,
  ad_group.name,
  ad_group_criterion.system_serving_status,
  ad_group_criterion.keyword.match_type,
  ad_group_criterion.approval_status,
  ad_group_criterion.final_urls,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM keyword_view
WHERE segments.date DURING LAST_7_DAYS
  AND ad_group_criterion.status != 'REMOVED'

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT ad_group_criterion.keyword.text,
    campaign.name,
    ad_group.name,
    ad_group_criterion.system_serving_status,
    ad_group_criterion.keyword.match_type,
    ad_group_criterion.approval_status,
    ad_group_criterion.final_urls,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros
  FROM keyword_view
  WHERE segments.date DURING LAST_7_DAYS
    AND ad_group_criterion.status != 'REMOVED'
"
}'

عبارات البحث

شاشة نظرة عامة على عبارات البحث التلقائية في واجهة المستخدم

شاشة واجهة المستخدم

طلب بحث واجهة برمجة التطبيقات

مورّد Google Analytics

SELECT search_term_view.search_term,
  segments.keyword.info.match_type,
  search_term_view.status,
  campaign.name,
  ad_group.name,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.advertising_channel_type
FROM search_term_view
WHERE segments.date DURING LAST_7_DAYS

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT search_term_view.search_term,
    segments.keyword.info.match_type,
    search_term_view.status,
    campaign.name,
    ad_group.name,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.advertising_channel_type
  FROM search_term_view
  WHERE segments.date DURING LAST_7_DAYS
"
}'

الجماهير

شاشة "نظرة عامة على شرائح الجمهور" التلقائية في واجهة المستخدِم

تجدر الإشارة إلى أنّ Reporting API تعرض شرائح الجمهور حسب أرقام تعريف معاييرها. للحصول على الأسماء المعروضة، ابحث عن أرقام التعريف في الجداول المرجعية المتوفرة في صفحة الرموز والتنسيقات. يمكنك إيقاف تشغيل الحقل ad_group_criterion.type لتحديد نوع المعايير الذي سيتم استخدامه.

شاشة واجهة المستخدم

طلب بحث واجهة برمجة التطبيقات

مورّد Google Analytics

SELECT ad_group_criterion.resource_name,
  ad_group_criterion.type,
  campaign.name,
  ad_group.name,
  ad_group_criterion.system_serving_status,
  ad_group_criterion.bid_modifier,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.advertising_channel_type
FROM ad_group_audience_view
WHERE segments.date DURING LAST_7_DAYS

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT ad_group_criterion.resource_name,
    ad_group_criterion.type,
    campaign.name,
    ad_group.name,
    ad_group_criterion.system_serving_status,
    ad_group_criterion.bid_modifier,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.advertising_channel_type
  FROM ad_group_audience_view
  WHERE segments.date DURING LAST_7_DAYS
"
}'

العمر (الخصائص الديمغرافية)

شاشة نظرة عامة على الخصائص الديمغرافية للعمر في واجهة المستخدم

شاشة واجهة المستخدم

طلب بحث واجهة برمجة التطبيقات

مورّد Google Analytics

SELECT ad_group_criterion.age_range.type,
  campaign.name,
  ad_group.name,
  ad_group_criterion.system_serving_status,
  ad_group_criterion.bid_modifier,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.advertising_channel_type
FROM age_range_view
WHERE segments.date DURING LAST_7_DAYS

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT ad_group_criterion.age_range.type,
    campaign.name,
    ad_group.name,
    ad_group_criterion.system_serving_status,
    ad_group_criterion.bid_modifier,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.advertising_channel_type
  FROM age_range_view
  WHERE segments.date DURING LAST_7_DAYS
"
}'

الجنس (الخصائص الديمغرافية)

شاشة نظرة عامة على الخصائص الديمغرافية للجنس في واجهة المستخدم

شاشة واجهة المستخدم

طلب بحث واجهة برمجة التطبيقات

مورّد Google Analytics

SELECT ad_group_criterion.gender.type,
  campaign.name,
  ad_group.name,
  ad_group_criterion.system_serving_status,
  ad_group_criterion.bid_modifier,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.advertising_channel_type
FROM gender_view
WHERE segments.date DURING LAST_7_DAYS

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT ad_group_criterion.gender.type,
    campaign.name,
    ad_group.name,
    ad_group_criterion.system_serving_status,
    ad_group_criterion.bid_modifier,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.advertising_channel_type
  FROM gender_view
  WHERE segments.date DURING LAST_7_DAYS
"
}'

المواقع الجغرافية

شاشة نظرة عامة على المواقع الافتراضية في واجهة المستخدم.

تجدر الإشارة إلى أنّ واجهة برمجة التطبيقات لإعداد التقارير تعرض المواقع الجغرافية حسب أرقام تعريف المعايير. للحصول على الأسماء المعروضة، ابحث عن campaign_criterion.location.geo_target_constant في بيانات الاستهداف الجغرافي، أو استخدِم واجهة برمجة التطبيقات لطلب البحث عن مورد geo_target_constant.

شاشة واجهة المستخدم

طلب بحث واجهة برمجة التطبيقات

مورّد Google Analytics

SELECT campaign_criterion.location.geo_target_constant,
  campaign.name,
  campaign_criterion.bid_modifier,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM location_view
WHERE segments.date DURING LAST_7_DAYS
  AND campaign_criterion.status != 'REMOVED'

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT campaign_criterion.location.geo_target_constant,
    campaign.name,
    campaign_criterion.bid_modifier,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros
  FROM location_view
  WHERE segments.date DURING LAST_7_DAYS
    AND campaign_criterion.status != 'REMOVED'
"
}'

البحث عن الثوابت الجغرافية

توفر صفحة الرموز والتنسيقات جداول مرجعية لمعظم الثوابت المستخدمة في واجهة برمجة التطبيقات. ومع ذلك، يمكنك أيضًا البحث ديناميكيًا عن بعض الثوابت باستخدام لغة طلب البحث في "إعلانات Google".

يوضح هذا النموذج كيفية البحث عن موقع باستخدام اسم المورد أو حسب الاسم المعروض.

حسب اسم المورد

ابحث عن ماونتن فيو، كاليفورنيا، باستخدام اسم المورد geoTargetConstants/1014044.

مورّد Google Analytics

SELECT geo_target_constant.canonical_name,
  geo_target_constant.country_code,
  geo_target_constant.id,
  geo_target_constant.name,
  geo_target_constant.status,
  geo_target_constant.target_type
FROM geo_target_constant
WHERE geo_target_constant.resource_name = 'geoTargetConstants/1014044'

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
\"query\": \"
  SELECT geo_target_constant.canonical_name,
    geo_target_constant.country_code,
    geo_target_constant.id,
    geo_target_constant.name,
    geo_target_constant.status,
    geo_target_constant.target_type
  FROM geo_target_constant
  WHERE geo_target_constant.resource_name = 'geoTargetConstants/1014044'
\"
}"

حسب الاسم المعروض

ابحث عن "ماونتن فيو" كاسم مدينة في الولايات المتحدة.

ملاحظة: عند طلب البحث عن مواقع جغرافية حسب الاسم، من المرجَّح أن تتلقّى العديد من النتائج المتطابقة. احرص على توضيح قائمة النتائج بشكل أكبر حسب الحاجة في رمز العميل.

مورّد Google Analytics

SELECT geo_target_constant.canonical_name,
  geo_target_constant.country_code,
  geo_target_constant.id,
  geo_target_constant.name,
  geo_target_constant.status,
  geo_target_constant.target_type
FROM geo_target_constant
WHERE geo_target_constant.country_code = 'US'
  AND geo_target_constant.target_type = 'City'
  AND geo_target_constant.name = 'Mountain View'
  AND geo_target_constant.status = 'ENABLED'

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
\"query\": \"
  SELECT geo_target_constant.canonical_name,
    geo_target_constant.country_code,
    geo_target_constant.id,
    geo_target_constant.name,
    geo_target_constant.status,
    geo_target_constant.target_type
  FROM geo_target_constant
  WHERE geo_target_constant.country_code = 'US'
    AND geo_target_constant.target_type = 'City'
    AND geo_target_constant.name = 'Mountain View'
    AND geo_target_constant.status = 'ENABLED'
\"
}"