管理广告组的脚本示例

以下部分展示了对广告组执行各种操作的脚本示例。

添加广告组

要添加广告组，请首先获取要将广告组添加到的市场活动。使用 CampaignSelector 对象选择市场活动。使用该 withIds 方法比在方法中 withCondition 传递市场活动名称提供更好的性能。

接下来，调用市场活动的 newAdGroupBuilder 方法以获取用于指定广告组属性的生成器。唯一必需的属性是广告组的名称 (查看 withName 方法) ，该属性在市场活动中必须是唯一的。如果未指定 CPC 值，则默认为帐号币种的最低出价金额。只有当市场活动未指定语言时，才需要指定语言;否则，它将继承市场活动的语言值。默认情况下，广告组的状态为暂停。

调用生成器的方法 build 将异步创建广告组;脚本会在脚本终止之前的某个时间点添加广告组，或者如果您调用了生成操作的方法之一，则会添加广告组。有关此过程的信息，请参阅什么是构建器？

function main() {
    // The ID of the campaign to add the ad groups to.
    // IDs in Scripts are string integers.
    var campaignId = 'CAMPAIGN ID GOES HERE';  
    var campaign = getCampaign(campaignId);

    // Ad groups to add.
    var adGroups = [];
    adGroups.push({
        name : 'AD GROUP NAME GOES HERE',
        cpc : 2.25,
        language : 'English' // Required if the campaign doesn't specify a language
    });
    adGroups.push({
        name : 'AD GROUP NAME GOES HERE',
        cpc : 1.25,
        language : 'English' // Required if the campaign doesn't specify a language
    });

    var operations = [];

    if (campaign != null)
    {
        for (var adGroup of adGroups) {
            var operation = addAdGroup(
                campaign, 
                adGroup.name, 
                adGroup.cpc, 
                adGroup.language);
            operations.push(operation);
        }
    }
    else {
        Logger.log("Unable to retrieve campaign, " + campaignId);
    }

    checkBuildStatus(operations, adGroups);
}

// Get the campaign using its ID.
function getCampaign(id) {
    var iterator = AdsApp.campaigns()
        .withIds([id])
        .get();

    // Return the campaign if it exists; otherwise, null.
    if (iterator.hasNext()) {
        return iterator.next();
    }
    else {
        return null;
    }
}

// Add the ad group to the specified campaign.
// Returns the builder's operation object, which you use to 
// check the status of the add operation.
function addAdGroup(campaign, name, cpc, language) {

    return campaign.newAdGroupBuilder()
        .withName(name)
        .withCpc(cpc)
        .withLanguage(language)
        .build();
}

// Check the ad group's build status.
function checkBuildStatus(operations, adGroups) {

    for (var i = 0; i < operations.length; i++) {
        if (!operations[i].isSuccessful()) {
            for (var error of operations[i].getErrors()) {
                Logger.log(`Failed to add, ${adGroups[i].name}. Error: ${error}`);
            }
        }
    }
}

获取所有广告组

要获取帐户中的所有广告组，请首先调用 AdsApp 对象的方法 adGroups 来获取选择器。然后，调用选择器的方法 get 以获取用于循环访问广告组列表的迭代器。由于该示例未指定任何筛选器，因此选择器会返回帐号中的所有广告组。要确定迭代器中的广告组数量，请调用迭代器的方法 totalNumEntities 。

function main() {
    // Gets all ad groups in the account.
    var iterator = AdsApp.adGroups().get();
    
    // Iterates through the list of ad groups and logs 
    // each ad group's name.
    while (iterator.hasNext()) {
        var adGroup = iterator.next();
    }
}

按名称获取广告组

若要按名称获取广告组，请首先调用 AdsApp 对象的方法 adGroups 来获取选择器。选择器包含许多用于过滤广告组列表的过滤方法。使用此方法筛选 withCondition 特定广告组名称的广告组。请注意，操作数和运算符区分大小写。

接下来，调用选择器的方法 get 以获取迭代器。广告系列中的广告组名称是唯一的，但多个广告系列可能具有同名的广告组。因此，如果仅按名称筛选，迭代器可能包含多个广告组。

如果要按名称获取特定广告系列中的广告组，请包含指定 withCondition 广告系列名称 (CampaignName = '<campaignnamegoeshere>') 的方法。

function main() {
    // The name of the ad group to get.
    var adGroupName = 'AD GROUP NAME GOES HERE';

    // Get the ad groups with the specified name.
    var iterator = AdsApp.adGroups()
          .withCondition(`Name = '${adGroupName}'`)
          .get();

    // Need a loop because multiple campaigns can have 
    // an ad group with the same name.
    while (iterator.hasNext()) {
        var adGroup = iterator.next();
    }
}

按 ID 获取广告组

如果有权访问广告组的 ID，请改用它。使用 ID 获取实体可提供更好的性能。不要使用 withCondition 筛选方法，而是使用该 withIds 方法。例如，withIds(['12345'])。

function main() {
    var adGroupId = '12345';

    var iterator = AdsApp.adGroups()
        .withIds([adGroupId])
        .get();

    if (iterator.hasNext()) {
        var adGroup = iterator.next();
    }
}

按名称获取特定市场活动中的广告组

function main() {
    var adGroupName = 'AD GROUP NAME GOES HERE';
    var campaignName = "CAMPAIGN NAME GOES HERE";

    var iterator = AdsApp.adGroups()
        .withCondition(`Name = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();

    if (iterator.hasNext()) {
        var adGroup = iterator.next();
    }
}

获取广告组的性能数据

要获取广告组的效果指标，请调用广告组的 getStats 方法。获取广告组时，需要指定所需指标数据的日期范围。可以使用预定义的文本（如 LAST_MONTH 或 TODAY）或开始日期和结束日期指定日期范围。若要指定日期范围，请在选择广告组时使用其中一种 forDateRange 方法 (请参阅 AdGroupSelector) 。

有关可以访问的指标列表，请参阅 Stats 对象。

function main() {
    var campaignName = 'CAMPAIGN NAME GOES HERE';
    var adGroupName = 'AD GROUP NAME GOES HERE';

    // Get the ad group. You need to specify the date range of the
    // performance data you want to get.
    var iterator = AdsApp.adGroups()
        .forDateRange('LAST_WEEK')
        .withCondition(`Name = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();
    
    // If the ad group is found, log some metrics.
    if (iterator.hasNext()) {
        var adGroup = iterator.next();
        var metrics = adGroup.getStats(); // Gets the performance metrics.
    }
}

暂停广告组

添加广告组时，其状态默认为“已暂停”。要启用广告组，请调用广告组的方法 enable 。要将广告组的状态更改为“已暂停”，请调用广告组的方法 pause 。要确定广告组的状态，请调用广告组的、 isPaused和isRemoved方法isEnabled。

function main() {
    var campaignName = 'CAMPAIGN NAME GOES HERE';
    var adGroupName = 'AD GROUP NAME GOES HERE';

    // Get the ad group. 
    var iterator = AdsApp.adGroups()
        .withCondition(`Name = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();

    if (iterator.hasNext()) {
        var adGroup = iterator.next();
        adGroup.pause();
    }
}

反馈

此页面是否有帮助？

上次更新时间为 2026-09-11