單一帳戶存取

文章
12/21/2023

如果您想要存取單一使用者帳戶，一切都會從 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() 的方法中指定效能資料行，也需要指定日期範圍。例如，如果您只想要 CTR 大於 .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() 方法。

Builder 物件包含方法，可用來設定您允許指定的所有物件屬性。它也包含 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;
    }    
}

寫入記錄檔

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

後續步驟

開始使用

分享方式：