管理广告的脚本示例

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

注意

在 2023 年 2 月 1 日之前将加大型文字广告升级为自适应搜索广告。在此日期之后，您将无法再创建新的或编辑现有的展开文字广告。有关详细信息，请参阅关于响应式搜索广告。
现有的加大型文字广告将继续投放，并且您将能够查看其效果报告。
您仍然可以暂停、启用或移除加大型文字广告。否则，尝试添加或更新加大型文字广告将导致 CampaignServiceAdTypeInvalid 错误。
了解有关此更改的详细信息。

添加广告

要添加广告，请首先获取要向其中添加广告的广告组。使用 AdGroupSelector 对象选择广告组。使用该 withIds 方法比在方法中 withCondition 传递广告组的名称具有更好的性能。

接下来，调用广告组的 newAd 方法以获取用于指定广告属性的生成器。与其他实体类型不同，该 newAd 方法返回一个 AdBuilderSpace 对象，该对象包含用于获取要创建的广告类型的生成器的方法。此示例添加了加大型文字广告，因此它调用 expandedTextAdBuilder 该方法以获取加大型文字广告构建器。

对于展开文字广告，您必须指定以下属性：

说明
FinalUrl
HeadlinePart1
HeadlinePart2

这些属性的组合唯一地定义了加大型文字广告。其他属性是可选的。

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

function main() {
    var adGroupId = "AD GROUP ID GOES HERE";
    var adGroup = getAdGroup(adGroupId);

    if (adGroup != null) {

        // Get an expanded text ad builder, specify the ad's 
        // properties, and add the ad to the build queue.
        var operation = adGroup.newAd().expandedTextAdBuilder()
            .withDescription("AD COPY GOES HERE")
            .withFinalUrl("https://contoso.com")
            .withHeadlinePart1("AD TITLE PART 1 GOES HERE")
            .withHeadlinePart2("AD TITLE PART 2 GOES HERE")
            .build();

        if (!operation.isSuccessful()) {
            for (var error of operation.getErrors()) {
                Logger.log(error);
            }
        }
    }
    else {
        Logger.log(`Failed to get ad group, ${adGroupId}.`);
    }
}

function getAdGroup(id) {
    var adGroups = AdsApp.adGroups()
        .withIds([id])
        .get();

    if (adGroups.hasNext()) {
        return adGroups.next();
    }
    else {
        return null;
    }
}

如果存在以前添加的广告，其必填字段组合的值相同，则服务不会添加该广告，而是返回之前添加的广告和 ID。但是，如果在同一构建队列中处理相同的广告，则第二个广告会失败，并显示 CampaignServiceDuplicateAd。例如，由于以下示例中的广告相同，因此其中一个广告失败。

    if (adGroup != null) {
        var adOperation = adGroup.newAd().expandedTextAdBuilder()
            .withDescription("ad copy")
            .withFinalUrl("https://contoso.com")
            .withHeadlinePart1("title part 1")
            .withHeadlinePart2("title part 2")
            .build();

        operations.push(adOperation);

        adOperation = adGroup.newAd().expandedTextAdBuilder()
            .withDescription("ad copy")
            .withFinalUrl("https://contoso.com")
            .withHeadlinePart1("title part 1")
            .withHeadlinePart2("title part 2")
            .build();

        operations.push(adOperation);
        
        for (var operation of operations) {
            if (!operation.isSuccessful()) {
                for (var error of operation.getErrors()) {
                    Logger.log(error);
                }
            }
        }
    }

获取广告

根据您在层次结构中的位置，有多种广告选项可供您投放广告。

从广告组获取广告

如果您有 AdGroup 对象，请调用对象的方法 ads 以获取属于该广告组的广告列表。此示例获取并打印组中的所有广告，但可以使用广告选择器的方法筛选广告列表。

function main() {
    var adGroups = AdsApp.adGroups()
        .withIds(["AD GROUP ID GOES HERE"])
        .get();

    if (adGroups.hasNext()) {
        var adGroup = adGroups.next();

        var ads = adGroup.ads().get();
        
        while (ads.hasNext()) {
            var ad = ads.next();

            if (ad.isType().expandedTextAd()) {
                var expandedAd = ad.asType().expandedTextAd();
            }
        }
    } 
}

从市场活动中获取广告

如果您有 Campaign 对象，请调用对象的方法 ads 以获取属于 Campaign 中广告组的广告列表。此示例使用广告选择器的方法 withCondition 将广告列表筛选为包含名称 foo 的广告组中的广告列表。

function main() {
    var campaigns = AdsApp.campaigns()
        .withIds(["CAMPAIGN ID GOES HERE"])
        .get();

    while (campaigns.hasNext()) {
        var campaign = campaigns.next();

        var ads = campaign.ads()
            .withCondition("AdGroupName CONTAINS_IGNORE_CASE 'foo'")
            .get();
        
        while (ads.hasNext()) {
            var ad = ads.next();

            if (ad.isType().expandedTextAd()) {
                var expandedAd = ad.asType().expandedTextAd();
            }
        }
    } 
}

获取帐户中的所有广告

要获取帐户中的所有广告，请调用 adsAdsApp 对象上的方法。您可以使用广告选择器的方法将广告列表筛选为广告系列、广告组或基于广告效果的广告列表。此示例获取来自该帐户的所有广告。

function main() {
    var ads = AdsApp.ads().get();

    while (ads.hasNext()) {
        var ad = ads.next();

        if (ad.isType().expandedTextAd()) {
            var expandedAd = ad.asType().expandedTextAd();
        }
    }
}

暂停广告

要暂停广告，请调用广告的方法 pause 。由于该 pause 方法位于基础 Ad 对象上，因此无需先获取派生对象。

如果要启用或移除广告，只需调用广告的 enable 或 remove 方法。要检查广告是否已启用或暂停，请调用 isEnabled OR isPaused 方法。

要获取具有特定状态的广告，请使用广告选择器的方法 withCondition 。例如，withCondition("Status = PAUSED)。

function main() {
    var ads = AdsApp.ads()
        .forDateRange("LAST_WEEK")
        .withCondition("AdGroupName CONTAINS_IGNORE_CASE 'foo'")
        .withCondition('Status = ENABLED')
        .withCondition('Clicks < 5')
        .get();
 
    while (ads.hasNext()) {
        var ad = ads.next();
        ad.pause();
    }
}

获取未经批准的广告

有关获取未经批准的广告的示例，请参阅发现未经批准的广告。

反馈

此页面是否有帮助？

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