Değişim

Google Ads komut dosyaları, Google Ads API'de bulunan genel değişiklikleri destekler. Kampanya oluşturma ve yönetme dahil olmak üzere, GoogleAdsService.mutate üzerinden gerçekleştirilebilecek çoğu işlem Google Ads komut dosyalarında da gerçekleştirilebilir.

Bu özellik Google Ads API'nin bu kadar büyük bir bölümüne erişim sağladığından, bu özelliği kullanmak için Google Ads API kurallarını temel düzeyde anlamanız önemlidir. Geliştirici jetonları ve yetkilendirme gibi birçok unsur sizin için Google Ads komut dosyaları tarafından işlendiği için 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

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

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 nesnenin içinde ne tür bir işlem gerçekleştirmekte olduğunuzu belirtirsiniz (bu örnekte campaignBudgetOperation). Daha sonra create ve remove ya da update ve updateMask özelliklerinin ikisini birden belirtirsiniz. create ve update içindeki belirli alanlar, üzerinde çalıştığınız kaynak türüne bağlıdır.

İşlem derleme

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ın listesini görmek için kampanya bütçesi için REST referans belgelerine bakabilir ve uygun alanları doldurabilir veya uygun bir nesne oluşturmak için komut dosyanıza özel JavaScript kodu yazabilirsiniz.

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

İşlem türleri

Oluştur

İşleminizde, oluşturmak istediğiniz kaynağın nesne temsilini ileterek create değerini belirtin.

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

Kaldır

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

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

Bir varlığın kaynak adını bilmiyorsanız Adsapp.search isteği kullanarak kaynağı alabilirsiniz.

Güncelle

İşleminizde, sistemin hangi nesneyi güncellemek istediğinizi belirleyebilmesi için kaynak adıyla belirtilen bir nesneyi ileterek update belirtin. 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. Kaynağın 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ü ne olursa olsun döndürülen değer MutateResult olur. Döndürülen kaynak adını kullanarak kaynağın dönüşümden sonraki mevcut durumunu sorgulayabilir ve işlemin başarılı olup olmadığını veya varsa hangi hataların oluştuğunu kontrol edebilirsiniz.

Bir sonucu kontrol etmek ve günlüklere bazı bilgileri yazdırmak için kullanılan temel akışı gösteren bir örneği aşağıda bulabilirsiniz:

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şlemin değiştirilmesini de destekler. Tek bir istekteki tam kampanya hiyerarşisi gibi, birbirine bağımlı varlıklar oluşturabilirsiniz. İsteğe bağlı olarak işlem kümesinin tamamını atomik yapabilirsiniz. Böylece 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 adet ve ilk işlemlerle aynı sırada olacak şekilde bir MutateResult nesne dizisidir.

Bu özellik Google Ads API özelliğiyle aynı şekilde çalışır. Bu nedenle geçici kimliklerin ve dikkat edilmesi gereken diğer noktaları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, Google Ads komut dosyaları belgelerinde ise lowerCamelCase kullanılmaktadır. Bu durumların her ikisi de Google Ads komut dosyalarında kabul edilir. Dolayısıyla, kodu doğrudan bu kılavuzdan kopyalayabilirsiniz.

Tek bir istekte birden çok 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ı, işlemler dizisini birinci bağımsız değişken ve isteğe bağlı bir ikinci bağımsız değişken olarak alır. Bunlara aşağıdakiler dahildir:

  • apiVersion: Komut dosyalarının varsayılanından farklı bir sürüm kullanmak istiyorsanız V16 gibi özel bir API sürümü belirtebilirsiniz. Şu an için herkese açık herhangi bir sürümü kullanabilirsiniz.
  • partialFailure: Bu alanın varsayılan değeri true'dir. true değerine 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. Böylece bu işlem seti atomik hale gelir.

Atom isteğinde kampanya bütçesi, kampanya ve reklam grubu oluşturan birden fazla işlemin yer aldığı bir örneği aşağıda bulabilirsiniz.

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});