google-ads-open-cli

Google Ads CLI 技能

你可以使用 google-ads-open-cli，这是一个只读的 Google Ads API（v23）命令行工具。使用它查询广告账号、获取效果统计数据，以及运行自定义 GAQL 查询。

快速开始

# Check if the CLI is available
google-ads-open-cli --help

# List accessible accounts
google-ads-open-cli customers

如果尚未安装 CLI，请进行安装：

npm install -g google-ads-open-cli

身份验证

此 CLI 使用 OAuth2 用户凭据（Google Ads API 不支持服务账号）。凭据存储在 ~/.config/google-ads-open-cli/credentials.json 中。

运行任何命令前，请先运行 google-ads-open-cli customers，确认凭据已配置。如果因凭据错误而失败，请让用户设置身份验证：

google-ads-open-cli auth login \
  --developer-token=xxx \
  --client-id=xxx \
  --client-secret=xxx

获取这些值的方法：

1. developer_token：登录 Google Ads 经理账号，并打开 API 中心。复制开发者令牌。
2. client_id 和 client_secret：前往 Google Cloud 控制台 > 凭据，创建一个 OAuth 客户端 ID（类型为桌面应用）。确保已启用 Google Ads API。

此操作会打开浏览器进行授权。确保用户使用有权访问所需 Google Ads 数据的 Google 账号登录。获批后，凭据会自动保存。之后的所有命令都会使用自动刷新的令牌。

对于 MCC（经理）账号，请在凭据文件中添加 "login_customer_id": "1234567890"。

或者，也可以设置 GOOGLE_ADS_ACCESS_TOKEN 和 GOOGLE_ADS_DEVELOPER_TOKEN 环境变量（适用于 CI/CD）。

实体层级

Manager Account (MCC)
 └── Customer Account (10-digit ID, e.g. 1234567890)
      ├── Campaign
      │    └── Ad Group
      │         ├── Ad (Ad Group Ad)
      │         └── Keyword (Ad Group Criterion)
      ├── Campaign Budget
      ├── Conversion Action
      ├── User List (remarketing)
      └── Asset (images, videos, sitelinks)

客户 ID 为 10 位数字。连字符会自动移除。

货币金额

Google Ads 使用微单位：1 个货币单位 = 1,000,000 微单位。CLI 返回的所有费用、出价和预算值均以微单位为单位。向用户显示货币金额时，务必除以 1,000,000。

输出格式

所有命令默认输出格式化的 JSON。使用 --format compact 可输出单行 JSON（适用于管道传递）。

内置命令

账号发现

# List all accessible accounts
google-ads-open-cli customers

# Get details for a specific account
google-ads-open-cli customer 1234567890

# List sub-accounts under an MCC
google-ads-open-cli account-hierarchy 1234567890

浏览实体

# Campaigns (filter by status: ENABLED, PAUSED, REMOVED)
google-ads-open-cli campaigns 1234567890
google-ads-open-cli campaigns 1234567890 --status ENABLED

# Get a specific campaign
google-ads-open-cli campaign 1234567890 98765

# Campaign budgets
google-ads-open-cli campaign-budgets 1234567890

# Ad groups (filter by campaign, status)
google-ads-open-cli ad-groups 1234567890 --campaign 98765

# Get a specific ad group
google-ads-open-cli ad-group 1234567890 11111

# Ads (filter by campaign, ad group, status)
google-ads-open-cli ads 1234567890 --campaign 98765 --ad-group 11111

# Get a specific ad (requires ad-group-id and ad-id)
google-ads-open-cli ad 1234567890 11111 22222

# Keywords
google-ads-open-cli keywords 1234567890 --campaign 98765 --status ENABLED

所有列表命令都支持 --limit <n>（默认值为 100）。

效果统计数据

统计命令需要 --start 和 --end 日期（YYYY-MM-DD）。返回行数最多为 --limit（默认值为 1000），按日期从新到旧排列（keyword-stats 则按展示次数从高到低排列）。如果 stderr 中出现与截断有关的 {"warning": ...}，请增大 --limit 或缩小日期范围，然后再计算总计：

# Campaign stats
google-ads-open-cli campaign-stats 1234567890 --start 2026-01-01 --end 2026-01-31

# Campaign stats with device segment
google-ads-open-cli campaign-stats 1234567890 --start 2026-01-01 --end 2026-01-31 --segments device

# Ad group stats (filter by --campaign and/or --ad-group)
google-ads-open-cli ad-group-stats 1234567890 --start 2026-01-01 --end 2026-01-31 --campaign 98765

# Ad-level stats (filter by --campaign and/or --ad-group)
google-ads-open-cli ad-stats 1234567890 --start 2026-01-01 --end 2026-01-31

# Keyword stats (sorted by impressions desc; filter by --campaign and/or --ad-group)
google-ads-open-cli keyword-stats 1234567890 --start 2026-01-01 --end 2026-01-31

campaign-stats --segments 可用的细分项：device、ad_network_type、day_of_week（用逗号分隔）。

统计命令的 --limit 默认值为 1000。

其他命令

# Audiences and remarketing lists
google-ads-open-cli audiences 1234567890
google-ads-open-cli user-lists 1234567890

# Assets and extensions
google-ads-open-cli assets 1234567890 --type SITELINK
google-ads-open-cli extensions 1234567890 --campaign 98765

# Conversions and billing
google-ads-open-cli conversion-actions 1234567890
google-ads-open-cli billing 1234567890

# Change history (default last 14 days, --days max 90)
google-ads-open-cli change-status 1234567890 --days 30 --limit 20

# Negative keyword lists
google-ads-open-cli negative-keywords 1234567890

素材类型：IMAGE、MEDIA_BUNDLE、TEXT、YOUTUBE_VIDEO、LEAD_FORM、CALL、CALLOUT、SITELINK、STRUCTURED_SNIPPET。

自定义 GAQL 查询

对于内置命令未涵盖的内容，可使用 query 命令作为补充。它会针对 Google Ads API 运行任意 GAQL（Google Ads 查询语言）。

google-ads-open-cli query <customer-id> "<GAQL>"

GAQL 语法

SELECT field1, field2, ...
FROM resource_name
WHERE conditions
ORDER BY field [ASC|DESC]
LIMIT count
PARAMETERS key=value

• SELECT 和 FROM 为必填项。WHERE、ORDER BY、LIMIT、PARAMETERS 均为可选项。
• 关键字（SELECT、FROM、WHERE 等）不区分大小写。
• 字段名称、资源名称和枚举值区分大小写。
• 不支持 OR 运算符——所有 WHERE 条件都会通过 AND 组合。
• 不支持 JOIN、GROUP BY、HAVING 或子查询。

WHERE 运算符

运算符	示例
=, !=, >, <, >=, <=	campaign.status = 'ENABLED'
IN, NOT IN	campaign.status IN ('ENABLED', 'PAUSED')
LIKE, NOT LIKE	campaign.name LIKE '%brand%'（不区分大小写）
REGEXP_MATCH	campaign.name REGEXP_MATCH '(?i)brand'
BETWEEN ... AND ...	segments.date BETWEEN '2026-01-01' AND '2026-01-31'
DURING	segments.date DURING LAST_30_DAYS
IS NULL, IS NOT NULL	ad_group_ad.ad.final_urls IS NOT NULL
CONTAINS ANY/ALL/NONE	用于重复字段

日期筛选

自定义范围：

WHERE segments.date BETWEEN '2026-01-01' AND '2026-01-31'

预定义范围（使用 DURING）：

• TODAY、YESTERDAY
• LAST_7_DAYS、LAST_14_DAYS、LAST_30_DAYS（不包括今天）
• THIS_MONTH、LAST_MONTH
• THIS_WEEK_SUN_TODAY、THIS_WEEK_MON_TODAY
• LAST_WEEK_SUN_SAT、LAST_WEEK_MON_SUN
• LAST_BUSINESS_WEEK

常见资源名称（FROM 子句）

实体： customer、campaign、campaign_budget、ad_group、ad_group_ad、ad_group_criterion、campaign_criterion

视图资源（用于指标）： keyword_view、search_term_view、geographic_view、gender_view、age_range_view、landing_page_view、ad_group_audience_view、shopping_performance_view、click_view

其他： change_status、change_event、conversion_action、asset、bidding_strategy、label、recommendation、shared_set、shared_criterion

常见指标

效果： metrics.impressions、metrics.clicks、metrics.cost_micros、metrics.ctr、metrics.average_cpc、metrics.average_cpm、metrics.interactions

转化： metrics.conversions、metrics.conversions_value、metrics.all_conversions、metrics.cost_per_conversion、metrics.conversion_rate、metrics.value_per_conversion

展示份额： metrics.search_impression_share、metrics.search_budget_lost_impression_share、metrics.search_rank_lost_impression_share、metrics.absolute_top_impression_percentage、metrics.top_impression_percentage

视频： metrics.video_views、metrics.video_view_rate、metrics.average_cpv

常见细分字段

日期： segments.date、segments.week、segments.month、segments.quarter、segments.year、segments.hour_of_day、segments.day_of_week

设备/网络： segments.device、segments.ad_network_type、segments.slot、segments.click_type

转化： segments.conversion_action、segments.conversion_action_name、segments.conversion_action_category

重要的 GAQL 规则

1. 日期细分字段必须搭配日期范围。 如果 SELECT 中包含 segments.date（或 segments.week、segments.month 等），WHERE 中必须包含有限的日期范围筛选条件。

2. WHERE 中的非日期细分字段必须出现在 SELECT 中。 例外：日期细分字段可以出现在 WHERE 中，而不必出现在 SELECT 中。

3. 默认会包含已移除的实体。 API 不会筛除已移除的实体。添加 campaign.status != 'REMOVED'（或等效条件），以匹配 Google Ads 界面中的行为。

4. 字段兼容性。 并非所有字段都可以同时选择。如果遇到字段不兼容的错误，请逐个移除字段，或查阅 Google Ads API 字段兼容性文档。

5. ORDER BY 字段必须出现在 SELECT 中。 只能按 SELECT 子句中出现的字段排序。

6. 关联资源。 即使父实体字段未出现在 FROM 中，也可以选择这些字段。例如，使用 FROM ad_group 时可以获取 campaign.name。

GAQL 查询示例

触发广告的搜索字词：

google-ads-open-cli query 1234567890 "SELECT search_term_view.search_term, search_term_view.status, campaign.name, ad_group.name, metrics.clicks, metrics.impressions, metrics.ctr, metrics.cost_micros FROM search_term_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.impressions DESC LIMIT 50"

按设备细分的广告系列效果：

google-ads-open-cli query 1234567890 "SELECT campaign.name, segments.device, metrics.impressions, metrics.clicks, metrics.ctr, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS AND campaign.status != 'REMOVED'"

展示份额分析：

google-ads-open-cli query 1234567890 "SELECT campaign.name, metrics.search_impression_share, metrics.search_budget_lost_impression_share, metrics.search_rank_lost_impression_share, metrics.clicks, metrics.impressions, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status = 'ENABLED' ORDER BY metrics.search_budget_lost_impression_share DESC"

落地页效果：

google-ads-open-cli query 1234567890 "SELECT landing_page_view.unexpanded_final_url, metrics.clicks, metrics.impressions, metrics.ctr, metrics.cost_micros, metrics.conversions FROM landing_page_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.clicks DESC LIMIT 20"

人口统计信息——年龄细分：

google-ads-open-cli query 1234567890 "SELECT ad_group_criterion.age_range.type, campaign.name, metrics.clicks, metrics.impressions, metrics.ctr, metrics.cost_micros FROM age_range_view WHERE segments.date DURING LAST_30_DAYS"

地理位置效果（按用户位置）：

google-ads-open-cli query 1234567890 "SELECT geographic_view.country_criterion_id, geographic_view.location_type, campaign.name, metrics.clicks, metrics.impressions, metrics.cost_micros FROM geographic_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.clicks DESC LIMIT 50"

广告文案效果（响应式搜索广告）：

google-ads-open-cli query 1234567890 "SELECT ad_group_ad.ad.responsive_search_ad.headlines, ad_group_ad.ad.responsive_search_ad.descriptions, ad_group_ad.ad.final_urls, ad_group_ad.status, metrics.clicks, metrics.impressions, metrics.ctr, metrics.cost_micros FROM ad_group_ad WHERE segments.date DURING LAST_30_DAYS AND ad_group_ad.status != 'REMOVED' AND ad_group_ad.ad.type = 'RESPONSIVE_SEARCH_AD' ORDER BY metrics.clicks DESC LIMIT 20"

转化操作审查：

google-ads-open-cli query 1234567890 "SELECT conversion_action.name, conversion_action.type, conversion_action.status, conversion_action.category, conversion_action.counting_type, conversion_action.click_through_lookback_window_days, conversion_action.view_through_lookback_window_days FROM conversion_action WHERE conversion_action.status = 'ENABLED'"

购物产品效果：

google-ads-open-cli query 1234567890 "SELECT segments.product_item_id, segments.product_title, metrics.clicks, metrics.impressions, metrics.ctr, metrics.cost_micros, metrics.conversions, metrics.conversions_value FROM shopping_performance_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.conversions_value DESC LIMIT 50"

账户级每日趋势：

google-ads-open-cli query 1234567890 "SELECT segments.date, metrics.clicks, metrics.impressions, metrics.ctr, metrics.cost_micros, metrics.conversions, metrics.conversions_value FROM customer WHERE segments.date DURING LAST_30_DAYS ORDER BY segments.date"

工作流指南

用户要求快速概览时

1. 运行 google-ads-open-cli customers 查找可访问的账号
2. 使用 campaign-stats 和近期日期范围获取效果概览
3. 展示数据，并将费用从微单位换算为货币金额

用户要求深入分析时

1. 先使用 campaign-stats 确定分析范围
2. 对表现不佳的广告系列，使用 ad-group-stats 或 keyword-stats 深入分析
3. 使用自定义 GAQL 查询进行专项分析（搜索字词、人口统计、展示份额、着陆页）
4. 交叉核对 conversion-actions，确认跟踪设置

用户询问内置命令未提供的特定指标时

使用 query 命令和 GAQL。常见场景：

• 搜索字词报告——使用 search_term_view
• 地理数据——使用 geographic_view
• 人口统计——使用 gender_view、age_range_view
• 着陆页——使用 landing_page_view
• 展示份额——从 campaign 中选择 metrics.search_impression_share 及相关字段
• 购物产品——使用 shopping_performance_view
• 变更历史记录——使用 change_event 查看详细日志

错误处理

• 身份验证错误——请用户确认其访问令牌和开发者令牌
• “field is not compatible”——某些字段不能同时选择；移除不兼容的字段后重试
• 结果为空——检查日期范围、状态筛选条件，以及账号是否包含所请求实体的数据
• “MISALIGNED_DATE_FOR_FILTER”——筛选 segments.month 或 segments.quarter 时，日期必须为该周期的第一天

API 文档参考

• google-ads-open-cli 文档
• Google Ads API 概览
• GAQL 参考
• GAQL 语法
• 资源字段参考（v23）
• GAQL 查询手册
• 细分规则