Değişim

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

Bu özellik, Google Ads API'nin çok büyük bir bölümüne erişim izni verdiğinden bu özelliği kullanabilmek için Google Ads API kuralları hakkında temel düzeyde bilgi sahibi olmanız önemlidir. Geliştirici jetonları ve yetkilendirme gibi birçok konu, Google Ads komut dosyaları tarafından sizin adınıza ele alındığından atlanabilir ancak geçerli bir değiştirme isteği oluşturmanız gerekir.

Bu kılavuza devam etmeden önce Google Ads API REST arayüzü hakkında bilgi sahibi olmanız gereken bazı temel kaynaklar aşağıda verilmiştir:

Temel örnek

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

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

AdsApp.mutate çağrısı, tek bir MutateOperation nesnesi temsil eden bir JSON nesnesi alır. Bu nesne içinde ne tür bir işlem gerçekleştireceğinizi belirtirsiniz. Bu örnekte campaignBudgetOperation. Ardından create, remove veya update ile updateMask'i belirtin. 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ğini kullanarak, tüm geçerli alanlarının listesini görmek için kampanya bütçesiyle ilgili REST referans dokümanlarını inceleyebilir, ardından uygun alanları doldurabilir veya uygun bir nesne oluşturmak için komut dosyanızda özel JavaScript kodu yazabilirsiniz.

Alternatif olarak, eklemek istediğiniz alanları seçerek dinamik bir istek gövdesi oluşturmanıza olanak tanıyan kampanya bütçesi için "Bunu dene" özelliğini kullanarak dinamik olarak bir işlem oluşturmayı deneyebilirsiniz. Ardından, oluşturulan sonuçtan işlemin içeriğini ayıklayabilir ve işlem türünü belirttikten sonra mutate çağrınıza ekleyebilirsiniz.

İşlem türleri

Oluştur

Oluşturmak istediğiniz kaynağı nesne temsilini ileterek işleminizde create değerini belirtin.

create işleminin bir örneği için yukarıya bakın.

Kaldır

İşleminizde remove'ü belirtin ve 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ı alabilirsiniz.

Güncelle

İşleminizde update'ü belirtin. Böylece sistem, hangi nesneyi güncellemek istediğinizi belirleyebilir. Ayrıca, değerlerini güncellemek istediğiniz tüm 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ş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üne bakılmaksızın, döndürülen değer bir MutateResult olur. Döndürülen kaynak adını kullanarak, değiştirme işleminden sonra kaynağın mevcut durumunu sorgulayabilir ve işlemin başarılı olup olmadığını veya varsa hangi hataların oluştuğunu kontrol edebilirsiniz.

Aşağıda, bir sonucu kontrol etme ve bazı bilgileri günlüklere yazdırma işleminin temel akışını 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 fazla işlem

Google Ads komut dosyaları, AdsApp.mutateAll yöntemiyle tek bir istekte birden fazla işlemin değiştirilmesini de destekler. Birbirine bağımlı varlıklar (ör. tek bir istekte tam kampanya hiyerarşisi) oluşturabilirsiniz. İsteğe bağlı olarak tüm işlem kümesini atomik yapabilirsiniz. Böylece, herhangi bir işlem başarısız olursa hiçbir işlem yapılmaz.

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

Bu özellik, Google Ads API özelliğiyle aynı şekilde çalışır. Bu nedenle, geçici kimliklerin ve diğer hususların tam açıklamasını görmek 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 dosyası dokümanlarında 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 diziye toplayın ve ardından AdsApp.mutateAll işlevini çağırın. mutateAll çağrısı, işlem dizisini ilk bağımsız değişken ve isteğe bağlı ikinci bir seçenek bağımsız değişkeni olarak alır. Örneğin:

  • apiVersion: Komut dosyalarının varsayılan sürümünden farklı bir sürüm kullanmak istiyorsanız V18 gibi özel bir API sürümü belirtebilirsiniz. Şu anda herkese açık olan tüm sürümleri kullanabilirsiniz.
  • partialFailure: Bu alanın varsayılan değeri true'dur. 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 olursa hiçbir işlem gerçekleştirilmez. Bu da bu işlem grubunu atomik hale getirir.

Aşağıda, atomik bir istekte kampanya bütçesi, kampanya ve reklam grubu oluşturan birden fazla işlem içeren 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});