管理廣告的腳本範例

發行項
11/13/2024

下列各節顯示針對廣告執行各種動作的腳本範例。

注意事項

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

新增廣告

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

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

針對展開的文字廣告，您必須指定下列屬性：

說明
FinalUrl
標題第 1 部分
標題第 2 部分

這些屬性的組合可唯一定義展開的文字廣告。其他屬性是選擇性的。

呼叫產生器的 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 方法。因為方法 pause 位於基底 Ad 物件上，所以您不需要先取得衍生物件。

如果您想要啟用或移除廣告，只要呼叫廣告的 enable 或 remove 方法即可。若要檢查廣告是否已啟用或暫停，請呼叫 isEnabled 或 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();
    }
}

取得未經核准的廣告

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

共用方式為