用于管理关键字的脚本示例

以下部分展示了对关键字执行各种操作的脚本示例。

添加关键字

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

接下来，调用广告组的 newKeywordBuilder 方法以获取用于指定关键字 (keyword) 属性的生成器。您必须指定的唯一属性是关键字 (keyword) 的文本 (查看withText方法) 。文本应包含匹配类型， (短语匹配类型使用方括号表示完全匹配类型，对于广泛匹配类型) ，文本应包含任何内容。

如果未指定每次点击费用值，则默认为广告组的每次点击费用值。默认情况下，启用关键字 (keyword) 的状态。

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

function main() {
    // The ID of the ad group to add the keywords to.
    // IDs in Scripts are string integers.
    var adGroupId = 'AD GROUP ID GOES HERE';  
    var adGroup = getAdGroup(adGroupId);

    // Keywords to add. Update as appropriate.
    var keywords = [];
    keywords.push({
        text : "keyword 1",
        cpc : 1.25,
        finalUrl : 'http://www.example.com'
    });
    keywords.push({
        text : "keyword 2",
        cpc : 1.5,
        finalUrl : 'http://www.example.com'
    });

    var operations = [];

    if (adGroup != null)
    {
        for (var keyword of keywords) {
            var operation = addKeyword(
                adGroup, 
                keyword.text, 
                keyword.cpc, 
                keyword.finalUrl);
            operations.push(operation);
        }
    }
    else {
        Logger.log("Unable to retrieve ad group, " + adGroupId);
    }

    checkBuildStatus(operations, keywords);
}

// Get the ad group using its ID.
function getAdGroup(id) {
    var iterator = AdsApp.adGroups()
        .withIds([id])
        .get();

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

// Add the keyword to the specified ad group.
function addKeyword(adGroup, text, cpc, finalUrl) {

    return adGroup.newKeywordBuilder()
        .withText(text)
        .withCpc(cpc)
        .withFinalUrl(finalUrl)
        .build();
}

// Check the keyword's build status.
function checkBuildStatus(operations, keywords) {

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

暂停关键字 (keyword)

添加关键字 (keyword) 时，其状态默认为“启用”。要暂停关键字 (keyword) ，请调用关键字 (keyword) 的方法pause。若要确定关键字 (keyword) 的状态，请调用关键字的 isEnabled 和 isPaused 方法。

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

    var iterator = AdsApp.keywords()
        .withCondition(`Text = '${keywordText}'`)
        .withCondition(`AdGroupName = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();

    while (iterator.hasNext()) {
        var keyword = iterator.next();
        keyword.pause();
    }
}

获取广告组中的所有关键字

要获取广告组中的所有关键字，请首先调用 AdsApp 对象的方法 keywords 来获取选择器。使用 withCondition 该方法指定广告组和市场活动。然后，调用选择器的方法 get 以获取用于循环访问关键字列表的迭代器。要确定迭代器中的关键字数，请调用迭代器的方法 totalNumEntities 。

如果有权访问关键字 (keyword) ID，请改用它们。使用 ID 获取实体可提供更好的性能。不要使用 withCondition 筛选方法，而是使用该 withIds 方法。例如，withIds(['12345'])。可以使用 ID 检索的实体数量有限制。

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

    var iterator = AdsApp.keywords()
        .withCondition(`AdGroupName = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();
        
    while (iterator.hasNext()) {
        var keyword = iterator.next();
    }
}

获取帐户中的所有关键字

脚本可以为帐户返回的关键字数是有限制的。该限制未定义，可能会更改。以下示例演示了如何处理帐户关键字过多的情况。该示例首先尝试在帐户级别提取所有关键字。如果由于“实体太多”错误而失败，它会尝试多次调用以按市场活动提取关键字，因为市场活动级别的实体通常较少。

有关使用 yield 关键字 (keyword) 的信息，请参阅在获取大型实体集时使用 yield 关键字 (keyword) 。

function* getEntities() {
    const applyConditions = _ => _
        .withCondition('CampaignStatus = ENABLED')
        .withCondition('AdGroupStatus = ENABLED')
        .withCondition('Status = ENABLED')
        .withCondition("CombinedApprovalStatus = DISAPPROVED");

    try {
        // Get the account's keywords. 
        const keywords = applyConditions(AdsApp.keywords()).get();

        while (keywords.hasNext()) {
            yield keywords.next();
        }
    } catch (e) {
        if (!e.message.startsWith('There are too many entities')) {
            throw e;
        }

        // If there are too many keywords at the account level,
        // get keywords by campaigns under the account.
        const campaigns = AdsApp.campaigns().get();

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

            const keywords = applyConditions(campaign.keywords()).get();

            while (keywords.hasNext()) {
                yield keywords.next();
            }
        }
    }
}

获取关键字 (keyword) 的性能数据

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

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

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

    // Get the keyword. You need to specify the date range of the
    // performance data you want to get.
    var iterator = AdsApp.keywords()
        .forDateRange('LAST_WEEK')
        .withCondition(`Text = '${keywordText}'`)
        .withCondition(`AdGroupName = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();

    // If the keyword is found, log some metrics.
    if (iterator.hasNext()) {
        var keyword = iterator.next();
        var metrics = keyword.getStats(); // Gets the performance metrics.
    }
}

更新关键字 (keyword) 的出价值。

有关如何更新关键字 (keyword) 的出价值的示例，请参阅调用 Google 服务。

反馈

此页面是否有帮助？

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