Değişim

Google Ads komut dosyaları, Google Ads API'de bulunan genel mutasyonlar için destek sunar. GoogleAdsService.mutate üzerinden gerçekleştirilebilen işlemlerin çoğu (ör. kampanya oluşturma ve yönetme) Google Ads komut dosyalarında da gerçekleştirilebilir.

Bu özellik, Google Ads API'nin büyük bir bölümüne erişime izin verdiğinden bu özelliği kullanmak için Google Ads API kuralları hakkında temel bir anlayışa sahip olmanız önemlidir. Geliştirici jetonları ve yetkilendirme gibi birçok yön atlanabilir. Bunlar Google Ads komut dosyaları tarafından sizin için işlenir ancak geçerli bir mutate isteği oluşturmanız gerekir.

Bu kılavuza devam etmeden önce Google Ads API REST arayüzüyle ilgili bilmeniz gereken bazı temel kaynakları aşağıda bulabilirsiniz:

Temel örnek

İşlevselliği göstermek için kampanya bütçesi oluşturan şu temel örneği inceleyin:

const budgetResult = AdsApp.mutate({
    campaignBudgetOperation: {
      create: {
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });

AdsApp.mutate çağrısı, tek bir MutateOperation öğesini temsil eden bir JSON nesnesi alır. Bu nesnede, gerçekleştirdiğiniz işlem türünü (bu örnekte campaignBudgetOperation) belirtirsiniz. Ardından create, remove veya hem update hem de updateMask değerini belirtirsiniz. create ve update içindeki belirli alanlar, üzerinde çalıştığınız kaynak türüne bağlıdır.

İşlem oluşturma

Geçerli bir işlem oluşturmak için kullanabileceğiniz birkaç strateji vardır. Kampanya bütçesi örneğine bağlı kalarak, geçerli tüm alanların listesini görmek için kampanya bütçesiyle ilgili REST referans belgelerine bakabilir, ardından uygun alanları doldurabilir veya uygun bir nesne oluşturmak için komut dosyanıza özel JavaScript kodu yazabilirsiniz.

Alternatif olarak, "Try this" (Bunu deneyin) özelliğini kullanarak kampanya bütçesi için dinamik bir işlem oluşturmayı deneyebilirsiniz. Bu özellik, eklemek istediğiniz alanları seçerek istek gövdesini dinamik olarak oluşturmanıza olanak tanır. Ardından, oluşturulan sonuçtan işlemin içeriğini çıkarabilir ve işlem türünü belirttikten sonra mutate çağrınıza ekleyebilirsiniz.

İşlem türleri

Oluştur

İşleminizde create değerini belirtin ve oluşturmak istediğiniz kaynağın nesne gösterimini iletin.

create işlemiyle ilgili bir örnek için yukarıya bakın.

Kaldır

İşleminizde remove değerini belirtin. Kaldırmak istediğiniz kaynağın kaynak adını iletin. Örneğin:

AdsApp.mutate({
    adGroupOperation: {
        remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
    }
});

Bir öğenin kaynak adını bilmiyorsanız Adsapp.search isteği kullanarak adını getirebilirsiniz.

Güncelle

İşleminizde update değerini belirtin. Kaynak adı belirtilmiş bir nesne iletin. Böylece sistem, hangi nesneyi güncellemek istediğinizi belirleyebilir. Ayrıca, değerlerini güncellemek istediğiniz alanları doldurun ve bu istekte tam olarak hangi alanları değiştirmeyi planladığınızı belirten bir updateMask belirtin. Kaynak adını güncelleme maskesine eklemeyin.

update işlemi örneği:

const campaignResult = AdsApp.mutate({
    campaignOperation: {
        update: {
            resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
            status: "PAUSED",
            name: "[Paused] My campaign"
        },
        updateMask: "name,status"
    }
});

Sonuçları işleme

İşlem türünden bağımsız olarak, dönüş değeri MutateResult olur. Döndürülen kaynak adını kullanarak, mutasyondan sonra kaynağın mevcut durumunu sorgulayabilir ve işlemin başarılı olup olmadığını ya da varsa hangi hataların oluştuğunu kontrol edebilirsiniz.

Aşağıda, bir sonucu kontrol etme ve günlüklerde bazı bilgileri yazdırma ile ilgili temel akışı gösteren bir örnek verilmiştir:

const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
    console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
    console.log("Errors encountered:");
    for (const error of result.getErrorMessages()) {
        console.log(error);
    }
}

Birden çok işlem

Google Ads komut dosyaları, AdsApp.mutateAll yöntemiyle tek bir istekte birden fazla işlemi değiştirme özelliğini de destekler. Tek bir istekte tam kampanya hiyerarşisi gibi birbirine bağlı öğeler oluşturabilirsiniz. İsteğe bağlı olarak, tüm işlemlerin atomik olmasını sağlayabilirsiniz. Bu durumda, işlemlerden herhangi biri başarısız olursa hiçbiri gerçekleştirilmez.

Döndürülen değer, sağladığınız her işlem için bir tane olmak üzere MutateResult nesnelerinden oluşan bir dizidir ve ilk işlemlerle aynı sıradadır.

Bu özellik, Google Ads API özelliğiyle aynı şekilde çalışır. Bu nedenle, geçici kimlikler ve diğer hususlarla ilgili ayrıntılı açıklama için Google Ads API'ye yönelik en iyi uygulamalar kılavuzuna bakın. Kılavuzda alan adlarını belirtmek için snake_case, Google Ads komut dosyaları dokümanlarında ise lowerCamelCase kullanıldığını unutmayın. Bu iki durum da Google Ads komut dosyalarında kabul edilir. Bu nedenle, kodu doğrudan söz konusu kılavuzdan kopyalayabilirsiniz.

Tek bir istekte birden fazla işlem yapmak için tüm işlemlerinizi bir dizide toplayın ve ardından AdsApp.mutateAll işlevini çağırın. mutateAll çağrısı, işlemler dizisini ilk bağımsız değişken olarak ve aşağıdakiler de dahil olmak üzere seçeneklerin isteğe bağlı ikinci bağımsız değişkenini alır:

  • apiVersion: Komut dosyalarının varsayılan sürümü dışında bir sürüm kullanmak isterseniz V20 gibi özel bir API sürümü belirtebilirsiniz. O sırada herkese açık olarak sunulan herhangi bir sürümü kullanabilirsiniz.
  • partialFailure: Bu alanın varsayılan değeri true'dir. true olarak ayarlanırsa geçerli işlemler gerçekleştirilir ve başarısız işlemler hata döndürür. false olarak ayarlanırsa herhangi bir işlem başarısız olduğunda hiçbir işlem gerçekleştirilmez. Bu da işlem grubunu etkili bir şekilde atomik hale getirir.

Aşağıda, atomik bir istekte kampanya bütçesi, kampanya ve reklam grubu oluşturan birden fazla işlemin yer aldığı bir örnek verilmiştir.

const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
    campaignBudgetOperation: {
      create: {
        resourceName: budgetId,
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });
operations.push({
    campaignOperation: {
      create: {
        resourceName: campaignId,
        name: 'New Campaign ' + new Date(),
        advertisingChannelType: 'SEARCH',
        manualCpc: {},
        campaignBudget: budgetId,
        advertisingChannelType: 'DISPLAY',
        networkSettings: {
          targetContentNetwork: true
        }
      }
    }
  });
operations.push({
    adGroupOperation: {
      create: {
        campaign: campaignId,
        name: 'New AdGroup ' + new Date(),
        optimizedTargetingEnabled: true
      }
    }
  });
const results = AdsApp.mutateAll(
    operations, {partialFailure: false});