管理廣告群組的指令碼範例

下列各節會顯示針對廣告群組執行各種動作的指令碼範例。

新增廣告群組

若要新增廣告群組，請先取得要新增廣告群組的廣告活動。使用 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 來取得迭代器。廣告活動內的廣告群組名稱為獨一無二，但多個廣告活動可能有相同名稱的廣告群組。因此，如果您只依名稱篩選，反覆運算器可能會包含多個廣告群組。

如果您想要依名稱取得特定廣告活動中的廣告群組，請加入指定 withCondition 廣告活動名稱 (CampaignName = '<campaignnamegoeshere>') 的方法。

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 獲取實體可提供更好的效能。請使用withIds方法，而不是使用withCondition篩選方法。例如，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