Sổ tay nấu ăn truy vấn

Hướng dẫn này cung cấp một tập hợp các truy vấn Ngôn ngữ truy vấn của Google Ads minh hoạ cách trả về cùng một dữ liệu với các màn hình trong giao diện người dùng Google Ads, cũng như cách tra cứu các hằng số địa lý. Bạn có thể sử dụng các truy vấn này như hiện có hoặc làm điểm xuất phát để tạo các truy vấn tuỳ chỉnh của riêng mình.

Lưu ý: Bạn cũng có thể sử dụng công cụ Trình tạo truy vấn tương tác để xác thực và tạo nguyên mẫu cho các truy vấn mới có tính tương tác.

Lưu ý quan trọng: Các thẻ cURL dưới đây minh hoạ cách sử dụng trực tiếp giao diện REST của API. Hãy xem trang search của hướng dẫn về Kiến trúc chuyển trạng thái đại diện (REST) để biết thêm thông tin chi tiết.

Tái tạo màn hình giao diện người dùng của Google Ads

Phần này giới thiệu các truy vấn API trả về cùng một dữ liệu như màn hình mặc định của giao diện người dùng Google Ads. Nếu bạn đang tạo một ứng dụng hiển thị các chỉ số và dữ liệu tương tự như Google Ads, thì các truy vấn này có thể giúp bạn lấy dữ liệu tương tự từ API.

Lưu ý: Trừ phi có quy định khác, tất cả truy vấn ngày trong hướng dẫn này sẽ trả về dữ liệu trong vòng 7 ngày qua theo mặc định.

Chiến dịch

Màn hình tổng quan mặc định về Chiến dịch trong giao diện người dùng.

Màn hình giao diện người dùng

Truy vấn API

Google Analytics 4 (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'
"
}'

Nhóm quảng cáo

Màn hình tổng quan về Nhóm quảng cáo mặc định trong giao diện người dùng.

Màn hình giao diện người dùng

Truy vấn API

Google Analytics 4 (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'
"
}'

Quảng cáo

Màn hình tổng quan mặc định về quảng cáo trong giao diện người dùng.

Xin lưu ý rằng truy vấn cụ thể này tìm nạp cụ thể các thành phần riêng lẻ của Quảng cáo văn bản mở rộng, hiển thị cùng nhau trong cột Quảng cáo của màn hình giao diện người dùng.

Màn hình giao diện người dùng

Truy vấn API

Google Analytics 4 (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'
"
}'

Từ khóa cho quảng cáo trên mạng Tìm kiếm

Màn hình tổng quan về Từ khoá cho quảng cáo trên Mạng Tìm kiếm mặc định trong giao diện người dùng.

Màn hình giao diện người dùng

Truy vấn API

Google Analytics 4 (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'
"
}'

Cụm từ tìm kiếm

Màn hình tổng quan về Cụm từ tìm kiếm mặc định trong giao diện người dùng.

Màn hình giao diện người dùng

Truy vấn API

Google Analytics 4 (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
"
}'

Đối tượng

Màn hình tổng quan về Đối tượng mặc định trong giao diện người dùng.

Xin lưu ý rằng API báo cáo trả về đối tượng theo mã tiêu chí. Để biết tên hiển thị, hãy tra cứu mã nhận dạng trong bảng tham chiếu được cung cấp trên trang Mã và định dạng. Bạn có thể khoá trường ad_group_criterion.type để xác định bảng loại tiêu chí cần sử dụng.

Màn hình giao diện người dùng

Truy vấn API

Google Analytics 4 (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
"
}'

Độ tuổi (Thông tin nhân khẩu học)

Màn hình tổng quan mặc định về Thông tin nhân khẩu học theo độ tuổi trong giao diện người dùng.

Màn hình giao diện người dùng

Truy vấn API

Google Analytics 4 (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
"
}'

Giới tính (Thông tin nhân khẩu học)

Màn hình tổng quan mặc định về thông tin nhân khẩu học theo giới tính trong giao diện người dùng.

Màn hình giao diện người dùng

Truy vấn API

Google Analytics 4 (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
"
}'

Địa điểm

Màn hình tổng quan về Vị trí mặc định trong giao diện người dùng.

Xin lưu ý rằng API báo cáo trả về vị trí theo mã tiêu chí. Để lấy tên hiển thị của chúng, hãy tra cứu campaign_criterion.location.geo_target_constant trong dữ liệu nhắm mục tiêu địa lý hoặc sử dụng API để truy vấn tài nguyên geo_target_constant.

Màn hình giao diện người dùng

Truy vấn API

Google Analytics 4 (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'
"
}'

Tra cứu hằng số địa lý

Trang Mã và định dạng cung cấp các bảng tham chiếu cho hầu hết các hằng số dùng trong API. Tuy nhiên, bạn cũng có thể tự động tra cứu một số hằng số bằng Ngôn ngữ truy vấn của Google Ads.

Mẫu này cho biết cách tra cứu một vị trí theo tên tài nguyên hoặc theo tên hiển thị của vị trí đó.

Theo tên tài nguyên

Tra cứu Mountain View, CA, theo tên tài nguyên geoTargetConstants/1014044.

Google Analytics 4 (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'
\"
}"

Theo tên hiển thị

Tra cứu "Mountain View" dưới dạng tên thành phố tại Hoa Kỳ.

Lưu ý: Khi truy vấn vị trí theo tên, bạn có thể nhận được nhiều kết quả phù hợp. Hãy nhớ phân biệt rõ hơn danh sách kết quả nếu thích hợp trong mã ứng dụng khách của bạn.

Google Analytics 4 (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'
\"
}"