本指南包含直接调用 REST 端点的示例,不使用 使用客户端库
前提条件
下面的所有示例都可以复制并粘贴到 bash 中 shell,使用 curl 命令。
您还需要获得开发者令牌,测试 就可以访问账号 至少包含一个客户账号的 Google Ads 经理账号。
环境变量
在下面输入账号凭据和 ID,然后复制粘贴到您的 终端来配置后续示例中使用的环境变量。 授权指南提供了有关如何生成 OAuth 2.0 访问令牌。
API_VERSION="17"
DEVELOPER_TOKEN="DEVELOPER_TOKEN "
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN "
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID "
CUSTOMER_ID="CUSTOMER_ID "
其他可选对象 ID
下面的一些示例适用于预先存在的预算或广告系列。如果您 要在这些示例中使用的现有对象的 ID,请在下面输入。
BUDGET_ID=
BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
否则,两个 Mutates - Creates examples 会创建新的预算 和广告系列。
搜索
查询实战宝典指南包含许多报告 示例,这些示例对应于一些默认的 Google Ads 屏幕, 与本指南中使用的环境变量相同。我们的交互式查询 Builder 工具 也是以交互方式构建自定义查询的绝佳资源。
分页
search
方法使用分页,固定页面大小为 10,000 个项目,
与 query
一起指定的 page_token
。
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \
--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'
",
"page_token":"${PAGE_TOKEN}"
}'
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'
流式
searchStream
方法会在单个响应中流式传输所有结果,因此
不支持“pageSize
”字段。
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'
"
}'
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'
转变
在一个文件中可以发送多个 mutate 操作(create
、update
或 remove
)
单个 JSON 请求正文。operations
创建
此示例会在单个请求中创建两项广告系列共享预算。
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
{
'create': {
'name': 'My Campaign Budget #${RANDOM}',
'amountMicros': 500000,
}
},
{
'create': {
'name': 'My Campaign Budget #${RANDOM}',
'amountMicros': 500000,
}
}
]
}"
下一个示例使用现有广告系列预算的 BUDGET_ID
;你可以
从上一步的输出中复制并粘贴内容。
BUDGET_ID=
BUDGET_ID
引用其他资源的资源是通过
资源名称。在下方制作的广告系列
通过字符串值的资源名称来引用 campaignBudget
。
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
{
'create': {
'status': 'PAUSED',
'advertisingChannelType': 'SEARCH',
'geoTargetTypeSetting': {
'positiveGeoTargetType': 'PRESENCE_OR_INTEREST',
'negativeGeoTargetType': 'PRESENCE_OR_INTEREST'
},
'name': 'My Search campaign #${RANDOM}',
'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}',
'targetSpend': {}
}
}
]
}"
更新
使用 update
操作更新现有对象的属性。下一个
使用现有广告系列您可以复制粘贴之前的
步骤的输出。
CAMPAIGN_ID=
CAMPAIGN_ID
所有更新均要求提供 updateMask
字段,这是以逗号分隔的
请求中应包含哪些 JSON 属性,
更新。属性列在 updateMask
中,但请求中不存在
被清除“updateMask
”中未列出的属性,但存在
会被忽略。
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
{
'update': {
'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}',
'name': 'A changed campaign name #${RANDOM}',
},
'updateMask': 'name'
}
],
}"
移除
以 remove
操作的形式指定对象的资源名称可移除对象。
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
{
'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}'
}
],
}"
部分失败
如果单个请求中有多个操作,可选择指定
partialFailure
。如果为 true
,则表示操作已成功执行,并且
无效操作会返回错误。如果为 false
,则表示请求中的所有操作
当且仅当它们都有效时,才会成功。
下一个示例使用现有广告系列;您可以从 创建示例输出。
CAMPAIGN_ID=
CAMPAIGN_ID
以下请求包含两项操作。前几次尝试更改
所提供广告系列的出价策略,而下一个会尝试移除
ID 无效的广告系列。由于第二个操作会导致错误(
广告系列 ID 无效),而且由于 partialFailure
设置为 false
,因此
第一次操作也会失败,现有广告系列的出价策略也是
未更新。
curl --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'partialFailure': false,
'operations': [
{
'update': {
'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}',
'manualCpc': {
'enhancedCpcEnabled': false
}
},
'updateMask': 'manual_cpc.enhanced_cpc_enabled'
},
{
'remove': 'customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID'
}
]
}"
分组操作
googleAds:mutate
方法支持使用
多种类型的资源您可以将多种不同类型的操作发送到
将应成组执行的一系列操作连在一起。
如果没有任何操作失败或全部失败(如果有的话),这组操作就会成功
单个操作失败。
此示例演示了如何创建广告系列预算、广告系列、广告组和 将广告集中为一组操作。每个连续操作都依赖于 。如果某个操作失败,则整个组操作都会失败。
负整数(-1
、-2
、-3
)在资源中用作占位符
并使用序列中的结果在运行时动态填充
操作。
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'mutateOperations': [
{
'campaignBudgetOperation': {
'create': {
'resourceName': 'customers/${CUSTOMER_ID}/campaignBudgets/-1',
'name': 'My Campaign Budget #${RANDOM}',
'deliveryMethod': 'STANDARD',
'amountMicros': 500000,
'explicitlyShared': false
}
}
},
{
'campaignOperation': {
'create': {
'resourceName': 'customers/${CUSTOMER_ID}/campaigns/-2',
'status': 'PAUSED',
'advertisingChannelType': 'SEARCH',
'geoTargetTypeSetting': {
'positiveGeoTargetType': 'PRESENCE_OR_INTEREST',
'negativeGeoTargetType': 'PRESENCE_OR_INTEREST'
},
'name': 'My Search campaign #${RANDOM}',
'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/-1',
'targetSpend': {}
}
}
},
{
'adGroupOperation': {
'create': {
'resourceName': 'customers/${CUSTOMER_ID}/adGroups/-3',
'campaign': 'customers/${CUSTOMER_ID}/campaigns/-2',
'name': 'My ad group #${RANDOM}',
'status': 'PAUSED',
'type': 'SEARCH_STANDARD'
}
}
},
{
'adGroupAdOperation': {
'create': {
'adGroup': 'customers/${CUSTOMER_ID}/adGroups/-3',
'status': 'PAUSED',
'ad': {
'responsiveSearchAd': {
'headlines': [
{
'pinned_field': 'HEADLINE_1',
'text': 'An example headline'
},
{
'text': 'Another example headline'
},
{
'text': 'Yet another headline'
}
],
'descriptions': [
{
'text': 'An example description'
},
{
'text': 'Another example description'
}
],
'path1': 'all-inclusive',
'path2': 'deals'
},
'finalUrls': ['https://www.example.com']
}
}
}
}
]
}"
账号管理
创建账户
使用 createCustomerClient
方法创建新账号。请注意,该网址
需要经理账号 ID,而不是客户账号 ID。新客户
账号是在经理账号下创建的。
curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'customerClient': {
'descriptiveName': 'My Client #${RANDOM}',
'currencyCode': 'USD',
'timeZone': 'America/New_York'
}
}"
列出可访问的账号
使用对 listAccessibleCustomers
方法的简单 GET
请求来获取列表
使用给定 OAuth 2.0 访问令牌访问的 Google Ads 账号。没有经理账号
或客户账号 ID。
curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
上传二进制资源
assets:mutate
方法用于上传和管理
素材资源。二进制数据(例如图像)被编码为
使用带填充的标准 base64 编码的字符串。标准或
无论有无填充,均可在网址中安全使用 base64 编码。
此示例对一个 1 像素的 GIF 进行编码,以保持示例简洁。实际上,
data
载荷要大得多。
使用 base64
命令行实用程序(
GNU 核心实用程序)
对 1 像素的 GIF 图片进行编码。
base64 1pixel.gif
采用 base64 编码的值在 API 请求中指定为 data
属性。
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
{
'create': {
'name': 'My image asset #${RANDOM}',
'type': 'IMAGE',
'imageAsset': {
'data': 'R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIA'
}
}
}
]
}"