管理關鍵字的指令碼範例

下列各節顯示針對關鍵字執行各種動作的指令碼範例。

新增關鍵字

若要新增關鍵字，請先取得要新增關鍵字的廣告群組。使用 AdGroupSelector 物件來選取廣告群組。比在 withIds 方法中 withCondition 傳遞廣告群組名稱，使用這個方法可提供更好的效能。

接著，呼叫廣告群組的 newKeywordBuilder 方法，以取得用來指定關鍵字屬性的建立器。您必須指定的唯一屬性是關鍵字的文字 (查看方法) withText 。文字應包含比對類型， (片語比對類型以引號括弧表示完全比對類型，以方括號表示廣泛比對類型) 。

如果您未指定每次點選成本值，則預設會是廣告群組的每次點選成本值。根據預設，關鍵字的狀態為啟用。

呼叫建置器的方法 build 會非同步建立關鍵字;指令碼會在指令碼終止之前的某個時間點，或如果您呼叫建置作業的其中一個方法，就會新增關鍵字。如需此程序的相關資訊，請參閱什麼是建置器？

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}`);
            }
        }
    }
}

暫停關鍵字

當您新增關鍵字時，其狀態預設為 [已啟用]。若要暫停關鍵字，請呼叫關鍵字的方法 pause 。若要判斷關鍵字的狀態，請呼叫關鍵字的和isPaused方法isEnabled。

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 。

如果您有關鍵字 ID 的存取權，請改用關鍵字 ID。使用 ID 獲取實體可提供更好的效能。請使用withIds方法，而不是使用withCondition篩選方法。例如，withIds(['12345'])。您可以使用識別碼擷取的實體數目有限制。

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 關鍵字的相關資訊，請參閱在取得大型實體集時使用 yield 關鍵字。

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();
            }
        }
    }
}

取得關鍵字的廣告成效資料

若要取得關鍵字的成效指標，請呼叫關鍵字的 getStats 方法。取得關鍵字時，您必須指定所需指標資料的日期範圍。您可以使用預先定義的常值指定日期範圍，例如 LAST_MONTH 或 TODAY，或使用開始和結束日期。若要指定日期範圍，請在選取關鍵字時使用其中一個 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.
    }
}

更新關鍵字的出價值。

如需如何更新關鍵字出價值的範例，請參閱呼叫 Google 服務。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-11