ラベル管理のスクリプト例

以下のセクションでは、ラベルに対してさまざまなアクションを実行するスクリプトの例を示します。

アカウントにラベルを追加する

ラベルを使用するには、まずアカウントにラベルを追加します。 1 つのアカウントには最大 100,000 個のラベルを追加できます。 ラベルを追加するには、 createLabel メソッドを使用します。 このメソッドは、ラベルの名前、説明、背景色を入力として受け取ります。

名前は必須ですが、説明と色はオプションです。 名前は大文字と小文字が区別され、80 文字を超えることはできず、アカウント内で一意である必要があります。 色は省略可能ですが、指定しない場合、サービスはランダムに色を選択します。 #RRGGBB 形式の 3 バイトの 16 進数 (CB0400 など) または 16 の既知の色名 (赤、黄、水色など) のいずれかを使用して色を指定できます。 色を指定する場合は、説明を指定する必要がありますが、空の文字列でもかまいません。

次の例は、 createLabel メソッドを呼び出す 3 つの方法を示しています。

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

}

キーワード (keyword) にラベルを適用する

ラベルは、キーワードなどのエンティティに適用する場合にのみ役立ちます。 キーワード (keyword) にラベルを適用するには、キーワード (keyword) の applyLabel メソッドを使用します。 1 つのキーワード (keyword)に最大 50 個のラベルを適用できます。 このメソッドは、ラベルの名前を入力として受け取ります。 ラベルの名前は大文字と小文字が区別され、アカウント内に存在する必要があり、キーワード (keyword)内で一意である必要があります。

次の例は、キーワード (keyword) にラベルを追加する方法、キーワード (keyword) のラベルを一覧表示する方法、キーワード (キーワード)からラベルを削除する方法を示しています。

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 列名を使用します。 1 つまたは複数の名前の配列を指定できます。 名前は大文字と小文字が区別され、厳密に一致し、アカウント内に存在する必要があります。 次の演算子を適用できます。

  • CONTAINS_ALL — 指定したラベルがすべて含まれている場合は、キーワード (keyword)を選択します
  • CONTAINS_ANY — 指定したラベルのいずれかが含まれている場合は、キーワード (keyword)を選択します
  • CONTAINS_NONE — 指定されたラベルが 1 つも含まれていない場合は、キーワード (keyword)を選択します

ラベルがアカウントに存在しない場合、セレクターは失敗し、エラーが返されることに注意してください。

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

}
  • Last updated on