单一帐户访问权限
如果想要访问单个用户帐户,一切都从 AdsApp 对象开始。
如何实现访问帐户中的实体?
使用 AdsApp
访问帐户中的所有实体。 对象包含每种类型的实体 (例如市场活动、广告组和关键字) 选择器方法。 选择器方法返回该实体类型的所有实体。 例如,若要获取帐户中的所有广告组,请调用 adGroups()
方法。
var iterator = AdsApp.adGroups().get();
但如果我需要特定实体或实体子集,该怎么办?
选择器提供了不同的方法来筛选实体列表。 可以使用选择器的 withIds()
方法按 ID 获取特定实体,也可以使用 withCondition()
指定用于选择实体的选择条件。 除负关键字 (keyword) 列表外,所有实体类型的选择器都提供筛选实体列表的功能。
使用点表示法将多个筛选器字符串在一起。 如果指定多个筛选器,则它们被视为 AND 操作 - 选择器仅返回与所有条件匹配的那些实体。
若要获取市场活动中的所有广告组,请使用 withCondition()
方法指定市场活动的名称。
var campaignName = 'My Campaign';
var iterator = AdsApp.adGroups()
.withCondition(`CampaignName = '${campaignName}'`)
.get();
有关可用于筛选实体列表的条件和运算符的列表,请参阅选择器的 withCondition()
方法。 例如,有关广告组条件的列表,请参阅广告组选择器的 withCondition 方法。
若要按 ID 获取广告组,请使用 withIds()
方法指定要获取的广告组。
var ids = ["123456789"];
var iterator = AdsApp.adGroups()
.withIds(ids)
.get();
或者,可以按名称获取广告组。
var campaignName = 'My Campaign';
var adGroupName = 'My AdGroup';
var iterator = AdsApp.adGroups()
.withCondition(`CampaignName = '${campaignName}'`)
.withCondition(`Name = '${adGroupName}'`)
.get();
有关选择器的详细信息,请参阅 什么是选择器?
如何实现使用选择器循环访问筛选的实体列表?
你没有。 选择器仅定义要获取的实体。 若要实际获取实体,请使用迭代器。 若要获取迭代器,请调用选择器的 get()
方法。
var ids = ["123456789"];
var iterator = AdsApp.adGroups()
.withIds(ids)
.get();
使用简单的 while 循环来循环访问实体列表。
while (iterator.hasNext()) {
var adGroup = iterator.next();
// Do something with the entity
}
有关迭代器的详细信息,请参阅 什么是迭代器?
如何实现获取实体的性能数据?
大多数实体允许你请求性能数据(如果可用)。 但首先,在指定选择器时,需要告诉脚本性能数据的日期范围。 若要指定日期范围,请使用预定义文本(如昨天或LAST_MONTH),或使用开始日期和结束日期。 有关详细信息,请参阅 forDateRange (string dateRange) 和 forDateRange (Object dateFrom、Object dateTo) 。
var campaignName = 'My Campaign';
var adGroupName = 'My AdGroup';
var iterator = AdsApp.adGroups()
.forDateRange('LAST_30_DAYS')
.withCondition(`CampaignName = '${campaignName}'`)
.withCondition(`Name = '${adGroupName}'`)
.get();
while (iterator.hasNext()) {
var adGroup = iterator.next();
var stats = adGroup.getStats();
}
如果在选择器的 withCondition()
方法中指定性能数据列,则还需要指定日期范围。 例如,如果仅希望 CTR 大于 0.22% 的广告组,则需要指定日期范围。
var startDate = {year: 2018, month: 6, day: 3};
var endDate = {year: 2018, month: 6, day: 13};
var iterator = AdsApp.adGroups()
.forDateRange(startDate, endDate)
.withCondition("Ctr > 0.22")
.get();
如何实现添加实体?
若要添加实体,请使用生成器对象。 若要获取生成器对象,请对要向其添加子级的父对象调用 new* 方法。 例如,若要向市场活动添加广告组,请调用市场活动的 newAdGroupBuilder()
方法。
builder 对象包含用于设置允许指定的所有对象的属性的方法。 它还包括用于 build()
创建实体的方法。 下面演示如何生成广告组。 (有关如何获取市场活动对象的信息,请参阅 按名称获取市场活动。)
var adGroupName = "My ad group";
var endDate = {year: 2018, month: 6, day: 13};
var customParameters = {key1: 'value1', key2: 'value2', key3: 'value3'};
var adGroupOperation = campaign.newAdGroupBuilder()
.withName(adGroupName)
.withStatus('ENABLED')
.withLanguage('English')
.withBiddingStrategy('MANUAL_CPC')
.withCpc(1.2)
.withCustomParameters(customParameters)
.withEndDate(endDate)
.build();
方法build
返回操作对象,可用于检查脚本是否成功创建了实体。 下面显示了典型的调用模式。
getResult
仅当想要访问新实体的属性时,才调用 方法。
if (adGroupOperation.isSuccessful()) {
var adGroup = adGroupOperation.getResult();
}
else {
for (var error of adGroupOperation.getErrors()) {
Logger.log(`${error}\n`);
}
}
有关生成器和调用操作方法时的性能注意事项的更多详细信息,请参阅 什么是生成器?
如何实现更新实体?
使用 builder 对象添加实体后,可以使用实体的 方法来更新其属性。 以下示例更新广告组的 CPC 出价金额。
var ids = ["123456789"];
var adGroups = AdsApp.adGroups()
.withIds(ids)
.get();
if (adGroups.hasNext()) {
var adGroup = adGroups.next();
adGroup.bidding().setCpc(2.5);
}
但如何知道更新是否正常工作?
如果尝试使用无效值更新属性,脚本会将错误写入更改日志,但它不会引发异常,因此脚本将继续执行。 如果属性包含新值,则不要在更新为检查后获取该属性;这样做会对性能产生负面影响。
function main() {
var id = "123456789";
var bidAmount = -2.5;
var keyword = getKeyword(id);
if (keyword != null) {
keyword.bidding().setCpc(bidAmount); // Bid is not set because bid amount is not valid
}
}
function getKeyword(id) {
var keywords = AdsApp.keywords()
.withIds([id])
.get();
if (keywords.hasNext()) {
return keywords.next();
}
else {
return null;
}
}
写入日志文件
脚本提供了一个日志文件,供你向其写入跟踪和调试信息。 有关信息,请参阅 更改日志和文本日志。