管理廣告的指令碼範例

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

注意事項

  • 在 2023 年 2 月 1 日之前，將延展型文字廣告升級為回應式搜尋廣告。 在此日期之後，您就無法再建立新項目或編輯現有的延展型文字廣告。 如需詳細資訊，請參閱 關於回應式搜尋廣告。
  • 現有的延展型文字廣告會繼續刊登，而且您將可以檢視其成效報告。
  • 您仍然可以暫停、啟用或移除延展型文字廣告。 否則，嘗試新增或更新延展型文字廣告 CampaignServiceAdTypeInvalid 會導致錯誤。
  • 深入了解此變更。

新增廣告

若要新增廣告，請先取得要新增廣告的廣告群組。 使用 AdGroupSelector 物件來選取廣告群組。 比在 withIds 方法中 withCondition 傳遞廣告群組名稱，使用這個方法可提供更好的效能。

接著，呼叫廣告群組的 newAd 方法，以取得您要用來指定廣告屬性的建立器。 與其他實體類型不同，這個 newAd 方法會傳回一個 AdBuilderSpace 物件，其中包含用於取得您要建立之廣告類型的建立器的方法。 此範例會新增延展型文字廣告，因此它會呼叫 expandedTextAdBuilder 方法來取得延展型文字廣告建立器。

對於延展型文字廣告，您必須指定下列屬性：

  • 描述
  • FinalUrl
  • 標題第 1 部分
  • 標題Part2

這些屬性的組合唯一定義了延展型文字廣告。 其他屬性則為選用。

呼叫建置器的方法 build 會非同步建立廣告;指令碼會在指令碼終止之前的某個時間點新增廣告，或者如果您呼叫建置作業的其中一個方法，就會新增廣告。 如需此程序的相關資訊，請參閱 什麼是建置器？

function main() {
    var adGroupId = "AD GROUP ID GOES HERE";
    var adGroup = getAdGroup(adGroupId);

    if (adGroup != null) {

        // Get an expanded text ad builder, specify the ad's 
        // properties, and add the ad to the build queue.
        var operation = adGroup.newAd().expandedTextAdBuilder()
            .withDescription("AD COPY GOES HERE")
            .withFinalUrl("https://contoso.com")
            .withHeadlinePart1("AD TITLE PART 1 GOES HERE")
            .withHeadlinePart2("AD TITLE PART 2 GOES HERE")
            .build();

        if (!operation.isSuccessful()) {
            for (var error of operation.getErrors()) {
                Logger.log(error);
            }
        }
    }
    else {
        Logger.log(`Failed to get ad group, ${adGroupId}.`);
    }
}

function getAdGroup(id) {
    var adGroups = AdsApp.adGroups()
        .withIds([id])
        .get();

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

如果先前新增的廣告且 [必要欄位組合] 的值相同，服務就不會新增廣告，而是傳回先前新增的廣告和識別碼。 不過，如果在相同的組建佇列中處理相同的廣告，則第二個廣告會因 CampaignServiceDuplicateAd 而失敗。 例如，由於下列範例中的廣告相同，導致其中一個廣告失敗。

    if (adGroup != null) {
        var adOperation = adGroup.newAd().expandedTextAdBuilder()
            .withDescription("ad copy")
            .withFinalUrl("https://contoso.com")
            .withHeadlinePart1("title part 1")
            .withHeadlinePart2("title part 2")
            .build();

        operations.push(adOperation);

        adOperation = adGroup.newAd().expandedTextAdBuilder()
            .withDescription("ad copy")
            .withFinalUrl("https://contoso.com")
            .withHeadlinePart1("title part 1")
            .withHeadlinePart2("title part 2")
            .build();

        operations.push(adOperation);
        
        for (var operation of operations) {
            if (!operation.isSuccessful()) {
                for (var error of operation.getErrors()) {
                    Logger.log(error);
                }
            }
        }
    }

取得廣告

根據您位於階層中的位置，您有數個取得廣告的選項。

從廣告群組取得廣告

如果您有 AdGroup 物件，請呼叫物件的方法 ads 以取得屬於該廣告群組的廣告清單。 此範例會取得並列印群組中的所有廣告，不過您可以使用廣告選取器的方法來篩選廣告清單。

function main() {
    var adGroups = AdsApp.adGroups()
        .withIds(["AD GROUP ID GOES HERE"])
        .get();

    if (adGroups.hasNext()) {
        var adGroup = adGroups.next();

        var ads = adGroup.ads().get();
        
        while (ads.hasNext()) {
            var ad = ads.next();

            if (ad.isType().expandedTextAd()) {
                var expandedAd = ad.asType().expandedTextAd();
            }
        }
    } 
}

從廣告活動取得廣告

如果您有 Campaign 物件，請呼叫物件的方法 ads 以取得屬於廣告活動中廣告群組的廣告清單。 此範例使用廣告選取器的方法 withCondition ，將廣告清單篩選為廣告群組中含有名稱 foo 的廣告。

function main() {
    var campaigns = AdsApp.campaigns()
        .withIds(["CAMPAIGN ID GOES HERE"])
        .get();

    while (campaigns.hasNext()) {
        var campaign = campaigns.next();

        var ads = campaign.ads()
            .withCondition("AdGroupName CONTAINS_IGNORE_CASE 'foo'")
            .get();
        
        while (ads.hasNext()) {
            var ad = ads.next();

            if (ad.isType().expandedTextAd()) {
                var expandedAd = ad.asType().expandedTextAd();
            }
        }
    } 
}

取得帳戶中的所有廣告

若要取得帳戶中的所有廣告，請在 AdsApp 物件上呼叫ads方法。 您可以使用廣告選取器的方法，將廣告清單篩選為廣告活動、廣告群組或根據廣告成效。 此範例會從帳戶取得所有廣告。

function main() {
    var ads = AdsApp.ads().get();

    while (ads.hasNext()) {
        var ad = ads.next();

        if (ad.isType().expandedTextAd()) {
            var expandedAd = ad.asType().expandedTextAd();
        }
    }
}

暫停廣告

若要暫停廣告，請呼叫廣告的方法 pause 。 由於方法位於基底 Ad 物件上，因此pause您不需要先取得衍生物件。

如果您想要啟用或移除廣告，只要呼叫廣告的 enable 或 remove method 即可。 若要檢查廣告是否已啟用或暫停，請呼叫 isEnabled OR isPaused 方法。

若要取得特定狀態的廣告，請使用廣告選取器的方式 withCondition 。 例如，withCondition("Status = PAUSED)。

function main() {
    var ads = AdsApp.ads()
        .forDateRange("LAST_WEEK")
        .withCondition("AdGroupName CONTAINS_IGNORE_CASE 'foo'")
        .withCondition('Status = ENABLED')
        .withCondition('Clicks < 5')
        .get();
 
    while (ads.hasNext()) {
        var ad = ads.next();
        ad.pause();
    }
}

取得不核准的廣告

如需取得未核准廣告的範例，請參閱 探索未核准的廣告。

  • Last updated on