管理標籤的腳本範例

下列各節顯示針對標籤執行各種動作的腳本範例。

將標籤新增至帳戶

若要使用標籤，請先將標籤新增至您的帳戶。 您最多可以將 100,000 個標籤新增至帳戶。 若要新增標籤，請使用 createLabel 方法。 方法會將標籤的名稱、描述和背景色彩作為輸入。

名稱是必要的，但描述和色彩是選擇性的。 名稱區分大小寫、不能超過 80 個字元，而且在帳戶內必須是唯一的。 雖然色彩是選擇性的，但如果您未指定，服務會為您選擇隨機色彩。 您可以在表單中使用三位元組十六進位數位來指定色彩 #RRGGBB (，例如，CB0400) 或 16 個已知色彩名稱之一，例如紅色、黃色和青色。 如果您指定色彩，則必須指定描述，但可能是空字串。

下列範例顯示呼叫 方法的 createLabel 三種方式。

function main() {

    AdsApp.createLabel("foo");
    AdsApp.createLabel("bar", "a descriptive description", "aqua");
    AdsApp.createLabel("foo foo", "", "#FF0000");

}

列出帳戶的標籤

若要取得帳戶中的標籤清單，請使用 labels 方法。 您可以使用 =、CONTAINS 和 STARTS_WITH 等標準字串運算子，依標籤的名稱篩選清單。

function main() {

    // Gets all the labels in the account
    var accountLabels = AdsApp.labels()
        .get();  
    
    Logger.log(`selector returned ${accountLabels.totalNumEntities()} labels that matched the selector's conditions`);

    // Gets all the labels in the account that contain foo in the name
    accountLabels = AdsApp.labels()
        .withCondition("Name CONTAINS 'foo'")
        .get();
    
    Logger.log(`selector returned ${accountLabels.totalNumEntities()} labels that matched the selector's conditions`);

    // Gets the first 15 labels in the account
    accountLabels = AdsApp.labels()
        .withLimit(15)
        .get();
    
    Logger.log(`selector returned ${accountLabels.totalNumEntities()} labels that matched the selector's conditions`);

    // Gets the first 15 labels in the account that contain foo in the name
    accountLabels = AdsApp.labels()
        .withCondition("Name CONTAINS 'foo'")
        .withLimit(15)
        .get();

    Logger.log(`selector returned ${accountLabels.totalNumEntities()} labels that matched the selector's conditions`);

    while (accountLabels.hasNext()){
        var label = accountLabels.next();
    }

}

將標籤套用至關鍵字

只有當您將標籤套用至關鍵字等實體時，標籤才有用。 若要將標籤套用至關鍵字，請使用 關鍵字的 applyLabel 方法。 您最多可以將 50 個標籤套用至關鍵字。 方法會接受 作為標籤名稱的輸入。 標籤的名稱會區分大小寫、必須存在於帳戶中，而且在 關鍵字內必須是唯一的。

下列範例示範如何將標籤新增至關鍵字、列出關鍵字的標籤，以及從關鍵字移除標籤。

function main() {

    // Get a keyword to add labels to
    var keyword = AdsApp.keywords().withIds(["12345"]).get().next();

    // Print the keyword's existing labels
    var labels = keyword.labels().get();
    printLabels(labels);

    // Add labels to the keyword
    keyword.applyLabel("foo");
    keyword.applyLabel("foo foo");
    keyword.applyLabel("bar");

    // Print the new list of labels
    labels = keyword.labels().get();
    printLabels(labels);

    // Remove labels from the keyword
    keyword.removeLabel("foo");
    keyword.removeLabel("bar");

    // Print the new list of labels
    labels = keyword.labels().get();
    printLabels(labels);

}

function printLabels(labels) {
    Logger.log(`keyword has ${labels.totalNumEntities()} labels`);
    
    while (labels.hasNext()){
        var label = labels.next();

        Logger.log(`name: ${label.getName()}
            description: ${label.getDescription()}
            color: ${label.getColor()}\n\n`);
    }
}

取得包含任何指定標籤的關鍵字

若要取得包含特定標籤名稱的關鍵字，請使用 KeywordSelector 物件的 withCondition () 方法。 使用 LabelNames 資料行名稱，依標籤名稱進行篩選。 您可以指定一或多個名稱的陣列。 名稱會區分大小寫、必須完全相符，而且必須存在於帳戶中。 您可以套用下列運算子：

• CONTAINS_ALL - 如果關鍵字包含所有指定的標籤，則選取關鍵字
• CONTAINS_ANY - 如果關鍵字包含任何指定的標籤，則選取關鍵字
• CONTAINS_NONE - 如果關鍵字未包含任何指定的標籤，則選取關鍵字

請注意，如果標籤不存在於帳戶中，選取器會失敗並傳回錯誤。

function main() {

    var keywords = AdsApp.keywords()
        .withCondition('LabelNames CONTAINS_ANY ["foo", "bar"]')
        .get();
    
    while (keywords.hasNext()){
        var keyword = keywords.next();

        var labels = keyword.labels().get();

        while (labels.hasNext()) {
            var label = labels.next();
        }
    }

}