Agent Skills
› NeverSight/learn-skills.dev
› google-ads
google-ads
GitHub通过Google Ads API查询广告活动、关键词及花费数据。支持使用curl和jq进行GAQL搜索流查询，获取点击、转化和成本指标，需配置OAuth令牌和开发者令牌等认证信息。
Trigger Scenarios
用户提及Google Ads或广告活动
查询广告花费、点击量、展示量或转化率
需要分析广告活动表现数据
Install
npx skills add NeverSight/learn-skills.dev --skill google-ads -g -y
SKILL.md
Frontmatter
{
"name": "google-ads",
"license": "Apache-2.0",
"metadata": {
"author": "acedatacloud",
"version": "1.0"
},
"connections": [
"google\/ads"
],
"description": "Query Google Ads campaigns, ad groups, keywords and spend via the Google Ads API (GAQL searchStream). Use when the user mentions Google Ads, ad campaigns, ad spend \/ cost, impressions \/ clicks \/ conversions on ads, or campaign performance.",
"when_to_use": "Trigger when the user wants Google Ads reporting — list accessible\ncustomers, campaign \/ ad-group \/ keyword performance, spend and\nconversions. Read via GAQL. Needs the OAuth token PLUS a platform\ndeveloper token and a login-customer-id; if those env vars are\nabsent the connector isn't fully provisioned yet — tell the user.\n",
"allowed_tools": [
"Bash"
]
}
Query the Google Ads API via curl + jq. Three credentials are needed:
$GOOGLE_ADS_TOKEN— the user's OAuth bearer (adwordsscope) →Authorization: Bearer $GOOGLE_ADS_TOKEN$GOOGLE_ADS_DEVELOPER_TOKEN— the platform's developer token (injected server-side) → headerdeveloper-token: $GOOGLE_ADS_DEVELOPER_TOKENlogin-customer-id— the manager (MCC) id under which calls are made; use the target customer id, or$GOOGLE_ADS_LOGIN_CUSTOMER_IDif set (digits only, no dashes).
API version: the base is
https://googleads.googleapis.com/<vNN>. Google ships a newvNNevery ~4 months and retires old ones — setVERto the current supported version (check developers.google.com/google-ads/api release notes); the example usesv18.
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).
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>)
curl -sS -H "$AUTH" -H "$DEV" "$BASE/customers:listAccessibleCustomers" | jq '.resourceNames'
Report with GAQL (searchStream)
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).
Gotchas
- Three headers, not one. Missing
developer-tokenorlogin-customer-idis the #1 cause of 401/403 here. - Customer ids are digits only in URLs/headers (strip the dashes from
123-456-7890). searchStreamreturns an array of chunks each with.results[]— flatten with.[].results[]?.- Cost is in micros of the account currency; divide by 1e6.
Version History
- e0220ca Current 2026-07-05 22:53
