單一帳戶存取

如果您想存取單一使用者帳戶，一切都從 AdsApp 物件開始。

如何？存取我帳戶中的實體？

用 AdsApp 來存取帳戶中的所有實體。該物件包含各種實體類型的選取器方法， (例如，廣告活動、廣告群組和關鍵字) 。選取器方法會傳回該實體類型的所有實體。例如，若要取得帳戶中的所有廣告群組，請呼叫 adGroups() 方法。

    var iterator = AdsApp.adGroups().get();

但是，如果我想要特定實體或實體子集，該怎麼辦？

選取器提供不同的方式來篩選實體清單。您可以使用選取器的方法 withIds() 以識別碼取得特定實體，或使用 withCondition() 來指定選取實體的選取準則。除了排除字彙清單之外，所有實體類型的選取器都提供篩選實體清單的功能。

使用點符號將多個篩選串在一起。如果您指定多個篩選條件，則會將它們視為 AND 運算 — 選取器只會傳回符合所有條件的實體。

若要取得廣告活動中的所有廣告群組，請使用 withCondition() 指定廣告活動名稱的方法。

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

如需可用來篩選實體清單的條件和運算子清單，請參閱選取器 withCondition() 方法。例如，如需廣告群組條件的清單，請參閱廣告群組選取器的 withCondition 方法。

若要依識別碼取得廣告群組，請使用 withIds() 指定要取得的廣告群組的方法。

    var ids = ["123456789"];
    var iterator = AdsApp.adGroups()
        .withIds(ids)
        .get();

或者，您可以依名稱取得廣告群組。

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

如需選取器的詳細資訊，請參閱什麼是選取器？

如何？使用選取器來逐一查看篩選的實體清單？

您不需要。選取器只會定義您想要取得的實體。若要實際取得實體，您可以使用反覆運算器。若要取得反覆運算子，請呼叫選取器的方法 get() 。

    var ids = ["123456789"];
    var iterator = AdsApp.adGroups()
        .withIds(ids)
        .get();

使用簡單的 while 迴圈來逐一查看實體清單。

    while (iterator.hasNext()) {
        var adGroup = iterator.next();
        
        // Do something with the entity
    }

如需反覆運算器的詳細資訊，請參閱什麼是反覆運算器？

如何？取得實體的效能資料？

如果有的話，大部分實體都可讓您要求效能資料。但首先，您必須在指定選取器時，告知指令碼效能資料的日期範圍。若要指定日期範圍，請使用預先定義的常值，例如 YESTERDAY 或 LAST_MONTH，或使用開始日期和結束日期。如需詳細資訊，請參閱 forDateRange (字串 dateRange) 和 forDateRange (Object dateFrom， Object dateTo) 。

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

    while (iterator.hasNext()) {
        var adGroup = iterator.next();
        var stats = adGroup.getStats();
    }

如果您在選取器 withCondition() 方法中指定成效資料欄位，也需要指定日期範圍。例如，如果您只想要廣告群組點選率大於 .22%，則需要指定日期範圍。

    var startDate = {year: 2018, month: 6, day: 3};
    var endDate = {year: 2018, month: 6, day: 13};

    var iterator = AdsApp.adGroups()
        .forDateRange(startDate, endDate)
        .withCondition("Ctr > 0.22")
        .get();

如何？新增實體？

若要新增實體，您可以使用建置器物件。若要取得建置器物件，請在您要新增子系的父物件上呼叫 new* 方法。例如，若要將廣告群組新增至廣告活動，請呼叫廣告活動的方法 newAdGroupBuilder() 。

產生器物件包含用來設定您可以指定之所有物件屬性的方法。它還包括 build() 用來建立實體的方法。下列說明如何建立廣告群組。 (如需如何取得行銷活動物件的相關資訊，請參閱依名稱取得行銷活動。)

        var adGroupName = "My ad group";
        var endDate = {year: 2018, month: 6, day: 13};
        var customParameters = {key1: 'value1', key2: 'value2', key3: 'value3'};

        var adGroupOperation = campaign.newAdGroupBuilder()
            .withName(adGroupName)
            .withStatus('ENABLED')
            .withLanguage('English')
            .withBiddingStrategy('MANUAL_CPC')
            .withCpc(1.2)
            .withCustomParameters(customParameters)
            .withEndDate(endDate)
            .build();

build此方法會傳回作業物件，您可以用來檢查指令碼是否成功建立實體。以下顯示典型的呼叫模式。只有在您想要存取新實體的屬性時，才呼叫 getResult 方法。

    if (adGroupOperation.isSuccessful()) {
        var adGroup = adGroupOperation.getResult();

    }
    else {
        for (var error of adGroupOperation.getErrors()) {
            Logger.log(`${error}\n`);
        }
    }

如需呼叫作業方法時的建置器和效能考量的詳細資訊，請參閱什麼是建置器？

如何？更新實體？

使用建置器物件新增實體之後，您可以使用實體的方法來更新其屬性。下列範例會更新廣告群組的每次點選成本出價金額。

    var ids = ["123456789"];
    var adGroups = AdsApp.adGroups()
        .withIds(ids)
        .get();

    if (adGroups.hasNext()) {
        var adGroup = adGroups.next();
        adGroup.bidding().setCpc(2.5);
    }

但是我要如何知道更新已正常運作呢？

如果您嘗試更新具有無效值的屬性，指令碼會將錯誤寫入變更記錄檔，但不會擲回例外狀況，因此指令碼會繼續執行。不要在更新屬性後取得屬性，以檢查屬性是否包含新值;這樣做會對效能造成負面影響。

function main() {
    var id = "123456789";
    var bidAmount = -2.5;  
    var keyword = getKeyword(id); 

    if (keyword != null) {
        keyword.bidding().setCpc(bidAmount);  // Bid is not set because bid amount is not valid
    }

}

function getKeyword(id) {
    var keywords = AdsApp.keywords()
        .withIds([id])
        .get();

    if (keywords.hasNext()) {
        return keywords.next();
    }
    else {
        return null;
    }    
}

寫入記錄檔

指令碼會提供記錄檔，供您寫入追蹤及偵錯資訊。如需詳細資訊，請參閱變更記錄和文字記錄。

後續步驟

開始使用

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-09-11