Google Ads API CLI和提示

人类使用的Google Ads界面。

这是一个正在进行中的项目，如果您发现任何错误或有任何建议，请提交问题。

功能

• 一个用于针对Google Ads API执行GAQL查询的命令行工具。类似于psql用于Google Ads API。
• 一个用于管理Google Ads资源的命令行工具。类似于kubectl用于Google Ads API。
• 集中配置，支持多个账户管理
• 自动更新刷新令牌
• Python API，集成Pandas

安装

pip install adsctl

入门

要求

• 使用Google Ads API所需的所有要求，包括开发者令牌和OAuth2凭据
• 请参阅Google Ads API快速入门以获取更多详细信息。

配置

此项目管理自己的配置文件。要创建配置文件，请运行

adsctl config

# Open the location of the config files
adsctl config explore

打开新的默认配置文件并填写您的凭据：开发令牌、客户端ID、客户端密钥和客户ID。

登录并获取刷新令牌

adsctl auth <path-to-secret.json>

令牌将自动保存在配置文件中。您可以通过运行以下命令查看它

# View config
adsctl config view

多个账户

您可以通过在配置文件中添加TOML部分来管理多个账户。

current_account = "default"

[... default account ...]

[accounts.another]
developer_token = ""
customer_id = ""
login_customer_id = ""

[accounts.another.oauth]
client_id = ""
client_secret = ""

设置当前账户

$ adsctl config set-account another
$ adsctl config get-account
another

GAQL提示

一个用于针对Google Ads API执行GAQL查询的交互式外壳。

$ gaql

>>> SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id
+----+-----------------------------+---------+-------------+
|    | resourceName                | name    |          id |
|----+-----------------------------+---------+-------------|
|  0 | customers/XXX/campaigns/YYY | name1   | 10000000000 |
|  1 | customers/XXX/campaigns/YYY | name2   | 10000000000 |
|  2 | customers/XXX/campaigns/YYY | name3   | 10000000000 |
+----+-----------------------------+---------+-------------+

默认情况下，它使用table格式，但您可以使用-o选项控制输出格式。

# Print the plain protobuf response
$ gaql -o plain

# Print the contents of a CSV file
$ gaql -o csv

您还可以运行单个内联命令并将输出重定向到文件。

gaql -c 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id' -o csv > my-query.csv

这假设只会返回表格，但在更复杂的查询中，包括其他资源或使用指标和段时，会创建多个表格。在这些情况下，使用-o csv-files标志根据表格名称将每个表格保存到不同的文件。

$ gaql -c 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id' -o csv-files

$ ls
campaign.csv

查询变量

您可以使用jinja语法指定一个或多个变量，这些变量将用-v选项中指定的值替换。

gaql -c 'SELECT campaign.id, campaign.name FROM campaign WHERE campaign.id = {{ id }} ORDER BY campaign.id' -v id=123456789

您还可以不使用命令直接传递-v并在此提示查询中使用这些变量。

$ gaql -v id=123456789 -v field=name

>>> SELECT campaign.id, campaign.{{ field }} FROM campaign WHERE campaign.id = {{ id }} ORDER BY campaign.id

其他选项

您可以使用-a和-i选项覆盖账户和客户ID。有关详细信息，请参阅gaql --help。

命令行界面（CLI）

广告管理

获取广告活动

```shell
adsctl get campaign

Name                                          Status             Id
--------------------------------------------  --------  -----------
Interplanetary Cruise Campaign #168961427368  Paused    20370195066
Interplanetary Cruise Campaign #168961215970  Paused    20379497161

状态管理

adsctl edit campaign -i <campaign-id> status enabled

adsctl edit campaign -i 20370195066 status enabled

adsctl get campaign

Name                                          Status             Id
--------------------------------------------  --------  -----------
Interplanetary Cruise Campaign #168961427368  Enabled   20370195066
Interplanetary Cruise Campaign #168961215970  Paused    20379497161

更新预算

adsctl edit campaign -i <campaign-id> budget <amount>

Python API

您还可以使用Python API轻松执行GAQL查询，并将结果作为Python字典或pandas DataFrame获取。

import adsctl as ads

# Read config file and creates the Google Ads client
google_ads = ads.GoogleAds()

# Execute GAQL query
get_campaigns_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 != '{{ status }}'
"""

tables = google_ads.query(get_campaigns_query, params={"status": "REMOVED"}})

# Print Pandas DataFrames
for table_name, table in tables.items():
    print(table_name)
    print(table, "\n")

campaign
                                 resourceName   status  ...                      name optimizationScore
0  customers/XXXXXXXXXX/campaigns/YYYYYYYYYYY  ENABLED  ...               my-campaign          0.839904
[1 rows x 6 columns]

metrics
  clicks costMicros       ctr    averageCpc impressions
0    210    6730050  0.011457  32047.857143       18330

campaignBudget
                                       resourceName amountMicros
0  customers/XXXXXXXXXX/campaignBudgets/ZZZZZZZZZZZ      1000000

免责声明

这不是官方的谷歌产品.

该存储库由谷歌员工维护，但不是受支持的谷歌产品。在此处，代码和问题由维护者和其他GitHub社区成员在尽力而为的基础上回答。