Değişim

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

Bu özellik, Google Ads API'nin büyük bir bölümüne erişim sağladığından, bu özelliği kullanmak için Google Ads API kuralları hakkında temel bilgilere sahip olmak önemlidir. Geliştirici jetonları ve yetkilendirme gibi birçok adım Google Ads komut dosyaları tarafından sizin için gerçekleştirildiğinden atlanabilir ancak geçerli bir değişiklik 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 bu temel örneği inceleyin:

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

AdsApp.mutate çağrısı, tek bir MutateOperation nesnesini temsil eden bir JSON nesnesi alır. Bu nesnede, hangi tür işlemi gerçekleştirdiğinizi belirtirsiniz. Bu örnekte, campaignBudgetOperation işlemi gerçekleştiriliyor. Ardından create, remove veya hem update hem de updateMask değerlerini belirtirsiniz. create ve update içindeki belirli alanlar, üzerinde çalıştığınız kaynağın 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ğinden devam edersek geçerli tüm alanların listesini görmek için kampanya bütçesiyle ilgili REST referans belgelerine bakabilir ve ardından uygun alanları doldurabilir ya da uygun bir nesne oluşturmak için komut dosyanıza özel JavaScript kodu yazabilirsiniz.

Alternatif olarak, kampanya bütçesi için"Bunu deneyin" özelliğini kullanarak dinamik bir şekilde işlem oluşturmayı deneyebilirsiniz. Bu özellik, eklemek istediğiniz alanları seçerek dinamik bir şekilde istek gövdesi oluşturmanıza olanak tanır. Ardından, işlemin içeriğini oluşturulan sonuçtan çı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 temsilini iletin.

create işlemiyle ilgili bir örnek için daha önce verilen snippet'e 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 bu adı getirebilirsiniz.

Güncelle

İşleminizde update değerini belirtin ve sistemin hangi nesneyi güncellemek istediğinizi belirleyebilmesi için belirtilen kaynak adını içeren bir nesne iletin. 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. Güncelleme maskesine kaynak adını eklemeyin.

update işlemine örnek:

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

Herkese açık kullanıcı adı sonuçları

İşlem türünden bağımsız olarak, döndürülen değer bir 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 etmeye ve günlüklerde bazı bilgileri yazdırmaya yönelik temel bir akışı gösteren ö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ştirmeyi de destekler. Tek bir istekte tam kampanya hiyerarşisi gibi birbirine bağlı öğeler oluşturabilirsiniz. İsterseniz tüm işlem grubunu atomik hale getirebilirsiniz. Böylece, işlemlerden biri başarısız olursa hiçbiri gerçekleştirilmez.

Dönüş değeri, 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 kimliklerin ve diğer hususların tam açıklaması için Google Ads API en iyi uygulamalar kılavuzuna bakın. Kılavuzda alan adlarını temsil etmek için snake_case kullanılırken Google Ads komut dosyaları belgelerinde lowerCamelCase kullanıldığını unutmayın. Bu iki durum da Google Ads komut dosyalarında kabul edilir. Bu nedenle, kodu doğrudan bu 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 yöntemini çağırın. mutateAll çağrısı, ilk bağımsız değişken olarak işlem dizisini ve isteğe bağlı ikinci bağımsız değişken olarak aşağıdakiler gibi seçenekleri alır:

  • apiVersion: Komut dosyalarının varsayılan sürümü dışında bir sürüm kullanmak istiyorsanız özel bir API sürümü (ör. V26) belirtebilirsiniz. O sırada herkese açık olan 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});