Google Ads 脚本支持 Google Ads API 中提供的通用更改操作。您可以在 Google Ads 脚本中执行通过 GoogleAdsService.mutate
执行的大多数操作,包括制作和管理广告系列。
由于此功能可访问 Google Ads API 的大部分内容,因此请务必先对 Google Ads API 惯例有基本的了解,然后才能使用此功能。很多方面都是可以跳过的,例如开发者令牌和 因为这些授权将由 Google Ads 脚本为您处理,但是您必须 形成有效的 mutate 请求
在继续阅读本指南之前,您应先熟悉以下有关 Google Ads API REST 接口的一些基本资源:
基本示例
为了演示该功能,我们以下面的基本示例为例,它创建了一个 广告系列预算:
const budgetResult = AdsApp.mutate({
campaignBudgetOperation: {
create: {
amountMicros: 10000000,
explicitlyShared: false
}
}
});
对
AdsApp.mutate
采用代表单个
MutateOperation
。在此对象中,
指明您执行的操作的类型(在本例中为
campaignBudgetOperation
。然后,您可以指定 create
、remove
,或者同时指定 update
和 updateMask
。create
和 update
中的特定字段
取决于您操作的资源的具体类型。
构建操作
您可以使用几种策略来构建有效操作。粘滞 对于广告系列预算示例,您可以查找 REST 参考 广告系列预算文档,查看 所有有效字段,然后填写相应的字段,或者自行编写 JavaScript 代码来构建适当的对象。
或者,您也可以尝试使用广告系列预算的“试用此功能”来动态构建操作,通过选择要添加的字段来动态构建请求正文。然后,您可以从生成的结果中提取操作内容,并在指定操作类型后将其添加到 mutate
调用中。
操作类型
创建
在操作中指定 create
,并传入要创建的资源的对象表示法。
有关 create
操作的示例,请参见上文。
移除
在操作中指定 remove
,并传入 资源
name,这是您要创建的资源
例如:
AdsApp.mutate({
adGroupOperation: {
remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
}
});
如果您不知道实体的资源名称,可以使用 Adsapp.search
请求提取该名称。
更新
在操作中指定 update
,并传入具有资源名称的对象
以便系统可以确定要
更新。此外,请填写所有您想更新
值,并指定一个 updateMask
,用于准确指明哪些字段
您计划在这项请求中进行的更改请勿在更新掩码中添加资源名称。
update
操作示例:
const campaignResult = AdsApp.mutate({
campaignOperation: {
update: {
resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
status: "PAUSED",
name: "[Paused] My campaign"
},
updateMask: "name,status"
}
});
处理结果
无论操作类型如何,返回值都是 MutateResult
。您可以使用返回的资源名称查询更改后资源的当前状态,并检查操作是否成功或是否发生了错误(如果有)。
以下示例展示了用于检查结果并将一些信息输出到日志的基本流程:
const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
console.log("Errors encountered:");
for (const error of result.getErrorMessages()) {
console.log(error);
}
}
多项操作
Google Ads 脚本还支持使用 AdsApp.mutateAll
方法在单个请求中更改多项操作。您可以在单个请求中创建相互依赖的实体,例如完整的广告系列层次结构。您可以选择将整组操作设为原子操作,这样,如果其中任何一个操作失败,则所有操作都不会执行。
返回值是一个 MutateResult
对象数组,每个对象对应于您提供的每项操作,且顺序与初始操作相同。
此功能的运作方式与 Google Ads API 功能相同,因此请参阅 Google Ads API 最佳实践指南,详细了解临时 ID 和其他注意事项;请注意,该指南使用 snake_case
表示字段名称,而 Google Ads 脚本文档使用 lowerCamelCase
。Google Ads 脚本接受这两种情况,因此您可以直接从该指南中复制代码。
如需在单个请求中执行多项操作,请将所有操作收集到一个数组中,然后调用 AdsApp.mutateAll
。mutateAll
调用将
作为第一个参数和可选的第二个参数
选项,包括:
apiVersion
:您可以指定自定义 API 版本,如V18
(如果您想使用 脚本默认值。您可以使用当时的任何公开版本。partialFailure
:此字段的默认值为true
。如果设置为true
,则系统会执行有效的操作,失败的操作会返回错误。如果设置为false
,那么,如果任何操作失败,则不会执行任何操作 使这组操作具有原子性。
下面的示例显示了多项操作,其中创建了广告系列预算 采用原子化请求的形式
const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
campaignBudgetOperation: {
create: {
resourceName: budgetId,
amountMicros: 10000000,
explicitlyShared: false
}
}
});
operations.push({
campaignOperation: {
create: {
resourceName: campaignId,
name: 'New Campaign ' + new Date(),
advertisingChannelType: 'SEARCH',
manualCpc: {},
campaignBudget: budgetId,
advertisingChannelType: 'DISPLAY',
networkSettings: {
targetContentNetwork: true
}
}
}
});
operations.push({
adGroupOperation: {
create: {
campaign: campaignId,
name: 'New AdGroup ' + new Date(),
optimizedTargetingEnabled: true
}
}
});
const results = AdsApp.mutateAll(
operations, {partialFailure: false});