Microsoft Advertising Betikleri için en iyi uygulamalar

Komut dosyalarınızın ve platformun performansını iyileştirmek için lütfen aşağıda özetlenen en iyi uygulamaları gözden geçirin ve takip edin.

Seçicilerle çalışma

Filtreleri kullanma

Varlıkları kendiniz filtrelemek yerine seçicinin filtrelerini kullanın. Seçiciler, kimliklere ve koşullara göre filtrelemenize olanak tanır. Örneğin, bir varlığın performansına (ortalama CPC'si 10'dan büyük olan iade kampanyaları), durumuna (duraklatılan kampanyalar), varlığın üst nesnesinin adına ve daha fazlasına göre filtreleme yapabilirsiniz.

Filtre kullanmanın faydaları:

  • Seçicinin döndürdüğü varlık sayısını yalnızca ihtiyacınız olan varlıklarla sınırlar.

  • Betiğin daha hızlı yürütülmesini sağlar (döndürülecek ve işlenecek daha az varlık)

  • Varlık okuma sınırlarına çarpma olasılığınızı azaltır (bkz.

Doğru yol

    var adGroups = AdsApp.adGroups()
        .withCondition('Status = PAUSED')
        .get();

    while (adGroups.hasNext()) {
        var adGroup = adGroups.next();
        // Do something with paused ad group.
    }

Yanlış yol

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

    while (adGroups.hasNext()) {
        var adGroup = adGroups.next();
        
        if (adGroup.isPaused() == true) {
            // Do something with paused ad group.
        }
    }

Varlık hiyerarşisinde çapraz geçiş yapma

Bir varlığın alt varlıklarını veya varlığın üst varlığını almak istiyorsanız, bunları almak için varlık hiyerarşisini geçmeyin.

Alt varlıkları almak için, alt varlığın koleksiyonunu istediğiniz düzeyde kullanın.

Doğru yol

    // Get all ads.
    var ads = AdsApp.ads().get();

    while (ads.hasNext()) {
        var ad = ads.next();
        // Do something with ad.
    }

Veya belirli bir kampanyadan reklam istiyorsanız:

    // Get all ads in the campaign, 'mycampaign'.
    var ads = AdsApp.ads()
        .withCondition("CampaignName = 'mycampaign'")
        .get();

    while (ads.hasNext()) {
        var ad = ads.next();
        // Do something with ad.
    }

Ya da kampanya nesnesine sahipseniz bir kampanyanın reklamlarını alabilirsiniz:

    // Get all ads in the campaign.
    var ads = campaign.ads().get();

    while (ads.hasNext()) {
        var ad = ads.next();
        // Do something with ad.
    }

Yanlış yol

    var campaigns = AdsApp.campaigns().get();

    while (campaigns.hasNext()) {
        var adGroups = campaigns.next().adGroups().get();
        
        while (adGroups.hasNext()) {
            var ads = adGroups.next().ads().get();

            while (ads.hasNext()) {
                var ad = ads.next();
                // Do something with ad.
            }
        }
    }

Aynı durum, bir varlığın üst bilgisini almak istediğinizde de geçerlidir. Üst öğeyi almak için hiyerarşiyi geçmek yerine, alt varlığın üst erişimci yöntemini kullanın.

Doğru yol

    // Get all ads.
    var ads = AdsApp.ads()
        .withCondition('Clicks > 5')
        .forDateRange('LAST_7_DAYS')
        .get();

    while (ads.hasNext()) {
        var ad = ads.next();
        
        // Do something with campaign and adGroup.
        var adGroup = ad.adGroup();
        var campaign = ad.campaign();
    }

Yanlış yol

    var campaigns = AdsApp.campaigns().get();

    while (campaigns.hasNext()) {
        var campaign = campaigns.next();
        var adGroups = campaign.adGroups().get();
        
        while (adGroups.hasNext()) {
            var adGroup = adGroups.next();
            var ads = adGroup.ads().get();

            while (ads.hasNext()) {
                var ad = ads.next();
                
                if ('<some condition is met>') {
                    // Do something with campaign and adGroup.
                }
            }
        }
    }

Mümkün olduğunda varlık kimliklerini kullanın

Varlıkları filtrelemek için kimlikleri kullanmak en iyi performansı sağlar.

Bu

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

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

Bundan daha iyi performans sağlar

    var adGroups = AdsApp.adGroups()
        .withCondition("Name = 'myadgroup'")
        .get();

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

Seçiciler ve gereksiz sayıda alma ile sıkı döngülerden kaçının

Tek bir varlık alan alma istekleriyle döngülerden kaçının. Örneğin, bir anahtar kelime performans raporu çalıştırdığınızı ve rapordaki anahtar kelimeleri güncellemek istediğinizi varsayalım. Rapordan bir satır almak, anahtar sözcüğü almak ve sonra da bu satırı güncelleştirmek yerine, rapordaki her satırda döngü yaparken anahtar sözcük kimliklerinin bir listesini oluşturmalısınız. Ardından, tüm anahtar kelimeleri tek bir alma isteğinde almak için kimlik listesini seçiciye iletin. Daha sonra anahtar kelime listesini yineleyebilir ve bunları güncelleyebilirsiniz.

Doğru yol

    var report = AdsApp.report('<report query goes here>');

    var rows = report.rows();
    var idLists = []; // an array where each element contains an array of IDs.
    var idList = [];  // array of IDs that's limited to maxCount.
    var maxCount = 10000;

    while (rows.hasNext()) {
        var row = rows.next();

        if (idList.length < maxCount) {
            idList.push(row['id']);
        }
        else {
            idLists.push(idList);
            idList = [];
        }
    }

    for (idList of idLists) {
        var keywords = AdsApp.keywords()
            .withIds(idList)
            .get();

        while (keywords.hasNext()) {
            var keyword = keywords.next();
            // update the keyword        
        }
    }

Yanlış yol

    var report = AdsApp.report('<report query goes here>');

    var rows = report.rows();

    while (rows.hasNext()) {
        var row = rows.next();

        var keyword = AdsApp.keywords()
            .withIds([row['id']])
            .get()
            .next();

        // update the keyword        
    }

forDateRange yöntemini, yalnızca varlığın getStats yöntemini çağırmayı planlıyorsanız dahil edin

Seçici forDateRange yönteminin çağrılması, seçicinin varlığın performans verilerini almasına neden olur. Bir varlığın performans verilerini almak pahalıdır, bu nedenle yalnızca varlığın yöntemini çağırmayı getStats ve verileri kullanmayı planlıyorsanız alın.

Bir varlık için belirttiğiniz tarih aralığı, o varlıktan eriştiğiniz üst veya alt varlıklar için geçerli değildir. Örneğin, bir reklam grubu alır ve ardından üst kampanyasını alırsanız ve kampanyanın performans metriklerine erişmeye çalışırsanız, çağrı başarısız olur.

Aşağıdaki campaignStats.getReturnOnAdSpend() örnekteki çağrı, tarih aralığı kampanya için değil reklam grubu için geçerli olduğu için başarısız olur.

    var myAdGroups = AdsApp.adGroups().
        .withCondition("CampaignName CONTAINS 'gen'")
        .forDateRange("LAST_7_DAYS")
        .get();

    while (myAdGroups.hasNext()) {
        var adGroup = myAdGroups.next();
        var campaign = adGroup.getCampaign();
        var campaignStats = campaign.getStats();
        var campaignROAS = campaignStats.getReturnOnAdSpend();
    }

Bunun çalışması için kampanya için bir seçici oluşturmanız gerekir.

    var myAdGroups = AdsApp.adGroups().
        .withCondition("CampaignName CONTAINS 'gen'")
        .forDateRange("LAST_7_DAYS")
        .get();

    while (myAdGroups.hasNext()) {
        var adGroup = myAdGroups.next();
        var campaign = AdsApp.campaigns()
            .withIds([adGroup.getCampaign().getId()])
            .forDateRange("LAST_7_DAYS")
            .get()
            .next();
        var campaignStats = campaign.getStats();
        var campaignROAS = campaignStats.getReturnOnAdSpend();
    }

Seçicide koşul olarak kullanılan bir varlığın özelliğini değiştirmeyin

Yineleyiciler, bir kerede öğelerin tamamı yerine yalnızca tek bir öğe yükleyerek bellek baskısını azaltır. Bu nedenle, seçicide koşul olarak kullandığınız bir özelliği değiştirmek beklenmedik davranışlara neden olabilir.

Doğru yol

    var adGroups = []; 

    var iterator = AdsApp.adGroups()
        .withCondition('Status = ENABLED')
        .get();

    while (iterator.hasNext()) {
        adGroups.push(iterator.next());
    }

    for (var adGroup of adGroups) {
        adGroup.pause();
    }

Yanlış yol

    var adGroups = AdsApp.adGroups()
        .withCondition('Status = ENABLED')
        .get();

    while (adGroups.hasNext()) {
        var adGroup = adGroups.next();
        adGroup.pause();
    }

Toplu güncelleştirmeler

Performansı artırmak için Betikler, derleme isteklerini toplu olarak işler. Bir derleme isteğinin işlem yöntemini çağırırsanız, Betikleri kuyruğa alınan derleme isteklerini hemen işlemeye zorlar ve herhangi bir performans kazanımını ortadan kaldırır. Birden fazla varlık oluşturuyorsanız, işlem yöntemlerini varlığı oluşturmak için kullandığınız döngüde yürütmeyin. Bu, aynı anda yalnızca bir varlık işlendiğinden düşük performansa yol açar. Bunun yerine, işlemlerin bir dizisini oluşturun ve derleme döngüsünden sonra bunları işleyin.

Doğru yol

    // An array to hold the operations, so you 
    // can process them after all the entities are queued.
    var operations = []; 

    // Create all the new entities.
    for (var i = 0; i < keywords.length; i++) {
        var keywordOperation = AdsApp.adGroups().get().next()
          .newKeywordBuilder()
          .withText(keywords[i])
          .build();
        operations.push(keywordOperation);
    }

    // Now call the operation method so the build requests
    // get processed in batches.
    for (var i = 0; i < operations.length; i++) {
        var newKeyword = operations[i].getResult();
    }

Yanlış yol

    for (var i = 0; i < keywords.length; i++) {
        var keywordOperation = AdsApp.adGroups().get().next()  // Get the first ad group
          .newKeywordBuilder()  // Add the keyword to the ad group
          .withText(keywords[i])
          .build();

        // Don't get results in the same loop that creates
        // the entity because Scripts then only processes one
        // entity at a time.
        var newKeyword = keywordOperation.getResult();
    }

Aynı durum, bir varlığı güncelleştirdiğinizde ve güncelleştirdiğiniz özelliği aldığınızda da geçerlidir. Aşağıdakileri yapmayın:

    var bidAmount = 1.2;

    while (keywords.hasNext()) {
        var keyword = keywords.next();

        keyword.bidding().setCpc(bidAmount);

        if (keyword.bidding().getCpc() != bidAmount) {
            Logger.log(`Failed to update bid amount for keyword, ${keyword.getText()} (${keyword.getId()})`);
        }
    }

Büyük varlık kümeleri alırken yield anahtar sözcüğünü kullanın

Çok sayıda varlık almanın ve bunları döngüde işlediğiniz tek bir listeye yüklemenin birkaç dezavantajı vardır:

  1. İsteğin boyutuna bağlı olarak, döngü başlamadan önce tüm varlıkları getirmek için n sayıda arka uç isteği gerekebilir. Hepsini işlemezseniz, işlenmemiş varlıkları elde etmek için kullanılan zaman ve bilgi işlem gücü boşa gider. Örneğin, 10 bin anahtar kelime alırsanız ve yalnızca 2 bin anahtar kelimeyi işledikten sonra döngü bozulursa, kalan 8 bin anahtar kelimeyi elde etmek için kullanılan zaman ve bilgi işlem gücü boşa harcanır.

  2. Listeyi oluşturmak, tüm varlıkları aynı anda tutmak için daha fazla bellek gerektirir.

Bu sorunları çözmek için, komut dosyanızın varlıkları isteğe bağlı olarak getirmesine veya bir anlamda yalnızca ihtiyaç duyulduğunda "tembelce" getirmesine olanak tanıyan yield anahtar sözcüğünü kullanın. Bu, komut dosyanızın şu anda gerekenden daha fazla çağrı yapmadığı ve büyük nesne listeleri arasında dolaşmadığı anlamına gelir.

Bu örnek, yield anahtar sözcüğünü kullanırken kontrol akışını göstermek için günlüğe kaydetmeyi içerir.

function main() {
    const keywords = getKeywords();

    //@ts-ignore <-- suppresses iterator error
    for (const keyword of keywords) {
        Logger.log("in for loop\n\n");
    }
}

// Note that you must use the yield keyword in a generator function - see the
// '*' at the end of the function keyword.

function* getKeywords() {
    const keywords = AdsApp.keywords()
        .withCondition("Status = ENABLED")
        .withCondition("CombinedApprovalStatus = APPROVED")
        .withLimit(10)
        .get();

    Logger.log(`total keywords in account: ${keywords.totalNumEntities()} \n\n`);

    while (keywords.hasNext()) {
        Logger.log("before next()\n\n");
        yield keywords.next();
        Logger.log("after next\n\n");
    }
}

Varlık sınırlarından kaçınmak için arama düzeni

Betiklerin bir hesap için döndürebileceği varlık sayısının bir sınırı vardır. İstek bu sınırdan daha fazlasını döndürürse, Betikler şu iletiyle bir hata oluşturur: Çok fazla varlık var. Aşağıdaki örnek, çok sayıda varlık alırken kullanmanız gereken çağırma desenini gösterir. Örnek, önce hesap düzeyindeki tüm anahtar kelimeleri getirmeyi dener. Bu başarısız olursa, kampanya düzeyinde genellikle daha az varlık olduğundan, kampanyaya göre anahtar kelimeleri getirmek için birden çok çağrı yapmayı dener. Gerekirse, bu kalıbı genellikle reklam grubu düzeyine kadar devam ettirebilirsiniz.

Verim anahtar kelimesini kullanma hakkında bilgi için bkz: Büyük varlık kümeleri alırken verim anahtar sözcüğünü kullanma.

function* getEntities() {
    const applyConditions = _ => _
        .withCondition('CampaignStatus = ENABLED')
        .withCondition('AdGroupStatus = ENABLED')
        .withCondition('Status = ENABLED')
        .withCondition("CombinedApprovalStatus = DISAPPROVED");

    try {
        // Get the account's keywords. 
        const keywords = applyConditions(AdsApp.keywords()).get();

        while (keywords.hasNext()) {
            yield keywords.next();
        }
    } catch (e) {
        if (!e.message.startsWith('There are too many entities')) {
            throw e;
        }

        // If there are too many keywords at the account level,
        // get keywords by campaigns under the account.
        const campaigns = AdsApp.campaigns().get();

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

            const keywords = applyConditions(campaign.keywords()).get();

            while (keywords.hasNext()) {
                yield keywords.next();
            }
        }
    }
}
  • Last updated on