広告グループ管理のスクリプト例

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

広告グループの追加

広告グループを追加するには、まず広告グループを追加するキャンペーンを取得します。キャンペーンを選択するには、 CampaignSelector オブジェクトを使用します。 withIds メソッドを使用すると、withCondition メソッドでキャンペーンの名前を渡すよりもパフォーマンスが向上します。

次に、キャンペーンの newAdGroupBuilder メソッドを呼び出して、広告グループのプロパティの指定に使用するビルダーを取得します。必須プロパティは広告グループの名前 ( withName メソッドを参照) のみであり、キャンペーン内で一意である必要があります。 CPC 値を指定しない場合、デフォルトはアカウントの通貨の最低入札額になります。キャンペーンで言語が指定されていない場合にのみ指定する必要があります;それ以外の場合は、キャンペーンの言語値を継承します。既定では、広告グループのステータスは [一時停止] です。

ビルダーの build メソッドを呼び出すと、広告グループが非同期的に作成されます。スクリプトは、スクリプトが終了する前のある時点で、またはビルド操作のメソッドのいずれかを呼び出した場合に、広告グループを追加します。このプロセスの詳細については、「ビルダーとは」を参照してください。

function main() {
    // The ID of the campaign to add the ad groups to.
    // IDs in Scripts are string integers.
    var campaignId = 'CAMPAIGN ID GOES HERE';  
    var campaign = getCampaign(campaignId);

    // Ad groups to add.
    var adGroups = [];
    adGroups.push({
        name : 'AD GROUP NAME GOES HERE',
        cpc : 2.25,
        language : 'English' // Required if the campaign doesn't specify a language
    });
    adGroups.push({
        name : 'AD GROUP NAME GOES HERE',
        cpc : 1.25,
        language : 'English' // Required if the campaign doesn't specify a language
    });

    var operations = [];

    if (campaign != null)
    {
        for (var adGroup of adGroups) {
            var operation = addAdGroup(
                campaign, 
                adGroup.name, 
                adGroup.cpc, 
                adGroup.language);
            operations.push(operation);
        }
    }
    else {
        Logger.log("Unable to retrieve campaign, " + campaignId);
    }

    checkBuildStatus(operations, adGroups);
}

// Get the campaign using its ID.
function getCampaign(id) {
    var iterator = AdsApp.campaigns()
        .withIds([id])
        .get();

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

// Add the ad group to the specified campaign.
// Returns the builder's operation object, which you use to 
// check the status of the add operation.
function addAdGroup(campaign, name, cpc, language) {

    return campaign.newAdGroupBuilder()
        .withName(name)
        .withCpc(cpc)
        .withLanguage(language)
        .build();
}

// Check the ad group's build status.
function checkBuildStatus(operations, adGroups) {

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

すべての広告グループを取得する

アカウント内のすべての広告グループを取得するには、まず AdsApp オブジェクトの adGroups メソッドを呼び出してセレクターを取得します。次に、セレクターの get メソッドを呼び出して、広告グループのリストを反復処理するために使用する反復子を取得します。この例ではフィルターを指定していないため、セレクターはアカウント内のすべての広告グループを返します。反復子内の広告グループの数を確認するには、反復子の totalNumEntities メソッドを呼び出します。

function main() {
    // Gets all ad groups in the account.
    var iterator = AdsApp.adGroups().get();
    
    // Iterates through the list of ad groups and logs 
    // each ad group's name.
    while (iterator.hasNext()) {
        var adGroup = iterator.next();
    }
}

名前で広告グループを取得する

名前で広告グループを取得するには、まず AdsApp オブジェクトの adGroups メソッドを呼び出してセレクターを取得します。セレクターには、広告グループのリストをフィルター処理するために使用するいくつかのフィルター方法が含まれています。 withCondition メソッドを使用して、特定の広告グループ名で広告グループをフィルタリングします。オペランドと演算子では大文字と小文字が区別されることに注意してください。

次に、セレクターの get メソッドを呼び出して反復子を取得します。キャンペーン内の広告グループ名は一意ですが、複数のキャンペーンで同じ名前の広告グループを設定することができます。このため、名前のみでフィルタリングすると、イテレータに複数の広告グループが表示されることがあります。

特定のキャンペーンから名前で広告グループを取得する場合は、キャンペーンの名前 (CampaignName = '<campaignnamegoeshere>') を指定する withCondition メソッドを含めます。

function main() {
    // The name of the ad group to get.
    var adGroupName = 'AD GROUP NAME GOES HERE';

    // Get the ad groups with the specified name.
    var iterator = AdsApp.adGroups()
          .withCondition(`Name = '${adGroupName}'`)
          .get();

    // Need a loop because multiple campaigns can have 
    // an ad group with the same name.
    while (iterator.hasNext()) {
        var adGroup = iterator.next();
    }
}

ID で広告グループを取得する

広告グループの ID にアクセスできる場合は、代わりに使用します。 ID を使用してエンティティを取得すると、パフォーマンスが向上します。 withCondition フィルターメソッドを使用する代わりに、withIds メソッドを使用します。たとえば、「 withIds(['12345']) 」のように入力します。

function main() {
    var adGroupId = '12345';

    var iterator = AdsApp.adGroups()
        .withIds([adGroupId])
        .get();

    if (iterator.hasNext()) {
        var adGroup = iterator.next();
    }
}

特定のキャンペーンから名前で広告グループを取得する

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

    var iterator = AdsApp.adGroups()
        .withCondition(`Name = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();

    if (iterator.hasNext()) {
        var adGroup = iterator.next();
    }
}

広告グループのパフォーマンスデータを取得する

広告グループのパフォーマンスメトリックを取得するには、広告グループの getStats メソッドを呼び出します。広告グループを取得する際に、必要な指標データの日付範囲を指定する必要があります。日付範囲は、LAST_MONTH や TODAY などの定義済みリテラル、または開始日と終了日を使用して指定できます。日付範囲を指定するには、広告グループを選択するときに forDateRange 方法のいずれかを使用します ( 「AdGroupSelector」を参照)。

アクセスできるメトリックのリストについては、 Stats オブジェクトを参照してください。

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

    // Get the ad group. You need to specify the date range of the
    // performance data you want to get.
    var iterator = AdsApp.adGroups()
        .forDateRange('LAST_WEEK')
        .withCondition(`Name = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();
    
    // If the ad group is found, log some metrics.
    if (iterator.hasNext()) {
        var adGroup = iterator.next();
        var metrics = adGroup.getStats(); // Gets the performance metrics.
    }
}

広告グループを一時停止する

広告グループを追加すると、そのステータスはデフォルトで [一時停止] になります。広告グループを有効にするには、広告グループの enable メソッドを呼び出します。広告グループのステータスを [一時停止] に変更するには、広告グループの pause メソッドを呼び出します。広告グループのステータスを確認するには、広告グループの isEnabled、 isPaused、 isRemoved メソッドを呼び出します。

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

    // Get the ad group. 
    var iterator = AdsApp.adGroups()
        .withCondition(`Name = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();

    if (iterator.hasNext()) {
        var adGroup = iterator.next();
        adGroup.pause();
    }
}

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-11