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ızV16
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ğeritrue
'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});