单一帐户访问权限

项目
11/13/2024

如果想要访问单个用户帐户，一切都从 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;
    }    
}

写入日志文件

脚本提供了一个日志文件，供你向其写入跟踪和调试信息。有关信息，请参阅更改日志和文本日志。

后续步骤

入门

通过