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. Google Ads komut dosyaları tarafından sizin adınıza yönetildiğinden geliştirici jetonları ve yetkilendirme gibi birçok husus 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üyle ilgili bilmeniz gereken bazı temel kaynaklar aşağıda verilmiştir:

• REST Arayüzü Tasarımı
• Kaynak Adları
• JSON eşlemeleri
• Mutate

Temel örnek

İşlevi 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 nesnesi temsil eden bir JSON nesnesi alır. Bu nesne içinde, hangi tür bir işlem gerçekleştirdiğ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ğın nesne temsilini ileterek işleminizde create değerini belirtin.

create işleminin bir örneğini yukarıda bulabilirsiniz.

Kaldır

Kaldırmak istediğiniz kaynağın kaynak adını ileterek işleminizde remove'ü belirtin. Ö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. Sistem, hangi nesneyi güncellemek istediğinizi belirleyebilmesi için kaynak adı belirtilen bir nesne gönderin. 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. Tek bir istekte tam bir kampanya hiyerarşisi gibi birbirine bağlı varlıklar oluşturabilirsiniz. İsteğe bağlı olarak tüm işlem grubunu atomik hale getirebilirsiniz. Böylece, işlemlerden 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 ve ilk işlemlerle aynı sırayla MutateResult nesnelerinden oluşan 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 olarak alır ve aşağıdakiler gibi seçeneklerden oluşan isteğe bağlı bir ikinci bağımsız değişken alır:

• apiVersion: Komut dosyalarının varsayılan sürümünden farklı bir sürüm kullanmak istiyorsanız V19 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});