Back to Details

google-ads

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Query the Google Ads API via 
curl + jq
. Three credentials are needed:
  • $GOOGLE_ADS_TOKEN
    — the user's OAuth bearer (
    adwords
    scope) → 
    Authorization: Bearer $GOOGLE_ADS_TOKEN
  • $GOOGLE_ADS_DEVELOPER_TOKEN
    — the platform's developer token (injected server-side) → header 
    developer-token: $GOOGLE_ADS_DEVELOPER_TOKEN
  • login-customer-id
    — the manager (MCC) id under which calls are made; use the target customer id, or 
    $GOOGLE_ADS_LOGIN_CUSTOMER_ID
    if set (digits only, no dashes).
API version: the base is 
https://googleads.googleapis.com/<vNN>
. Google ships a new 
vNN
every ~4 months and retires old ones — set 
VER
to the current supported version (check developers.google.com/google-ads/api release notes); the example uses 
v18
.
If 
$GOOGLE_ADS_DEVELOPER_TOKEN
is empty, the connector isn't fully provisioned — say so rather than calling the API (it would 401/DEVELOPER_TOKEN_NOT_APPROVED).
bash
VER="v18"; BASE="https://googleads.googleapis.com/$VER"
AUTH="Authorization: Bearer $GOOGLE_ADS_TOKEN"; DEV="developer-token: $GOOGLE_ADS_DEVELOPER_TOKEN"
通过
curl + jq
调用Google Ads API。需要以下三种凭据：
  • $GOOGLE_ADS_TOKEN
    — 用户的OAuth承载令牌（
    adwords
    权限范围）→ 请求头
    Authorization: Bearer $GOOGLE_ADS_TOKEN
  • $GOOGLE_ADS_DEVELOPER_TOKEN
    — 平台的开发者令牌（由服务器端注入）→ 请求头
    developer-token: $GOOGLE_ADS_DEVELOPER_TOKEN
  • login-customer-id
    — 发起调用时所属的管理账号（MCC）ID；可使用目标客户ID，若已设置
    $GOOGLE_ADS_LOGIN_CUSTOMER_ID
    则使用该值（仅含数字，无连字符）。
API版本说明：基础地址为
https://googleads.googleapis.com/<vNN>
。Google大约每4个月发布一个新的
vNN
版本并停用旧版本，请将
VER
设置为当前受支持的版本（可查看developers.google.com/google-ads/api的发布说明）；示例中使用的是
v18
。
若
$GOOGLE_ADS_DEVELOPER_TOKEN
为空，则连接器未完全配置完成——此时应告知用户这一情况，而非调用API（否则会返回401/DEVELOPER_TOKEN_NOT_APPROVED错误）。
bash
VER="v18"; BASE="https://googleads.googleapis.com/$VER"
AUTH="Authorization: Bearer $GOOGLE_ADS_TOKEN"; DEV="developer-token: $GOOGLE_ADS_DEVELOPER_TOKEN"

Customers the OAuth user can access (ids are returned as customers/<id>)

OAuth用户可访问的客户（ID格式为customers/<id>）

curl -sS -H "$AUTH" -H "$DEV" "$BASE/customers:listAccessibleCustomers" | jq '.resourceNames'
undefined
curl -sS -H "$AUTH" -H "$DEV" "$BASE/customers:listAccessibleCustomers" | jq '.resourceNames'
undefined

Report with GAQL (searchStream)

使用GAQL（searchStream）生成报告

bash
CID="1234567890"   # target customer id, digits only
curl -sS -H "$AUTH" -H "$DEV" -H "login-customer-id: ${GOOGLE_ADS_LOGIN_CUSTOMER_ID:-$CID}" \
  -H "Content-Type: application/json" -d '{
  "query":"SELECT campaign.name, metrics.cost_micros, metrics.clicks, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC"
}' "$BASE/customers/$CID/googleAds:searchStream" \
  | jq '.[].results[]? | {campaign: .campaign.name, cost_usd: (.metrics.costMicros|tonumber/1e6), clicks: .metrics.clicks, conv: .metrics.conversions}'
GAQL resources: 
campaign
, 
ad_group
, 
ad_group_criterion
(keywords), 
customer
. Cost is 
metrics.cost_micros
(÷ 1,000,000 = account currency).
bash
CID="1234567890"   # 目标客户ID，仅含数字
curl -sS -H "$AUTH" -H "$DEV" -H "login-customer-id: ${GOOGLE_ADS_LOGIN_CUSTOMER_ID:-$CID}" \
  -H "Content-Type: application/json" -d '{
  "query":"SELECT campaign.name, metrics.cost_micros, metrics.clicks, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC"
}' "$BASE/customers/$CID/googleAds:searchStream" \
  | jq '.[].results[]? | {campaign: .campaign.name, cost_usd: (.metrics.costMicros|tonumber/1e6), clicks: .metrics.clicks, conv: .metrics.conversions}'
GAQL可查询的资源包括：
campaign
（广告系列）、
ad_group
（广告组）、
ad_group_criterion
（关键词）、
customer
（客户）。成本字段为
metrics.cost_micros
（除以1,000,000即可转换为账户货币单位）。

Gotchas

注意事项

  • Three headers, not one. Missing 
    developer-token
    or 
    login-customer-id
    is the #1 cause of 401/403 here.
  • Customer ids are digits only in URLs/headers (strip the dashes from 
    123-456-7890
    ).
  • searchStream
    returns an array of chunks each with 
    .results[]
    — flatten with 
    .[].results[]?
    .
  • Cost is in micros of the account currency; divide by 1e6.
  • 需包含三个请求头，而非一个。缺少
    developer-token
    或
    login-customer-id
    是导致401/403错误的最常见原因。
  • 在URL和请求头中，客户ID必须仅含数字（需移除
    123-456-7890
    中的连字符）。
  • searchStream
    返回的是包含多个数据块的数组，每个数据块包含
    .results[]
    ——可使用
    .[].results[]?
    来扁平化数据。
  • 成本单位为账户货币的微单位；需除以1e6进行转换。