用于管理广告的脚本示例

2024-11-13

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

注意

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

添加广告

若要添加广告，请先获取要添加广告的广告组。使用 AdGroupSelector 对象选择广告组。 withIds与在方法中withCondition传递广告组的名称相比，使用方法可提供更好的性能。

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

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

说明
FinalUrl
标题部分1
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();
            }
        }
    } 
}

从市场活动获取广告

如果你有市场活动对象，请调用对象的 ads 方法以获取属于市场活动中广告组的广告列表。此示例使用广告选择器的 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 或 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();
    }
}

获取未批准的广告

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