查詢教戰手冊

本指南提供一組 Google Ads 查詢語言查詢，說明如何傳回與 Google Ads UI 畫面相同的資料，以及如何查詢地理常數。您可以直接使用這些查詢，也可以將其做為起點，自行建構自訂查詢。

複製 Google Ads UI 畫面

本節會展示 API 查詢，這些查詢會傳回與 Google Ads UI 預設畫面相同的資料。如果您要建構的應用程式會顯示類似 Google Ads 的指標和資料，這些查詢有助於您從 API 擷取類似的資料。

廣告活動

使用者介面中的預設廣告活動總覽畫面。

UI 畫面

Google Ads UI 廣告活動畫面

API 查詢

GAQL

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'
"
}'

廣告群組

使用者介面中的預設廣告群組總覽畫面。

UI 畫面

Google Ads UI 廣告群組畫面

API 查詢

GAQL

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 Ads 總覽畫面。

請注意，這項特定查詢會特別擷取展開式文字廣告的個別元件，這些元件會在 UI 畫面的「廣告」欄中一併顯示。

UI 畫面

Google Ads UI 廣告畫面

API 查詢

GAQL

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'
"
}'

搜尋關鍵字

UI 中的預設搜尋關鍵字總覽畫面。

UI 畫面

Google Ads UI 搜尋關鍵字畫面

API 查詢

GAQL

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'
"
}'

搜尋字詞

使用者介面中的預設搜尋字詞總覽畫面。

UI 畫面

Google Ads UI 搜尋字詞畫面

API 查詢

GAQL

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
"
}'

目標對象

使用者介面中的預設目標對象總覽畫面。

請注意，報表 API 會根據條件 ID 傳回目標對象。如要取得顯示名稱，請在「代碼和格式」頁面提供的參照表格中查詢 ID。您可以使用 ad_group_criterion.type 欄位來決定要使用哪種條件類型表格。

UI 畫面

Google Ads 使用者介面「目標對象」畫面

API 查詢

GAQL

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
"
}'

年齡 (客層)

使用者介面中的預設年齡客層總覽畫面。

UI 畫面

Google Ads UI 年齡畫面

API 查詢

GAQL

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
"
}'

性別 (客層)

使用者介面中的預設性別客層總覽畫面。

UI 畫面

Google Ads UI 性別畫面

API 查詢

GAQL

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
"
}'

位置

使用者介面中的預設「位置」總覽畫面。

請注意，報表 API 會依據條件 ID 傳回位置。如要取得顯示名稱，請在地理區域指定資料中查詢 campaign_criterion.location.geo_target_constant，或使用 API 查詢 geo_target_constant 資源。

UI 畫面

Google Ads UI 的「Locations」畫面

API 查詢

GAQL

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'
"
}'

查詢地理常數

「代碼和格式」頁面提供 API 中所用常數的參考表格。不過，您也可以使用 Google Ads 查詢語言，動態查詢部分常數。

本範例說明如何依照資源名稱或顯示名稱查詢位置。

依資源名稱

根據資源名稱 geoTargetConstants/1014044 查詢加州山景市。

GAQL

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'
\"
}"

依顯示名稱

查詢美國城市「山景城」的名稱。

GAQL

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'
\"
}"