Skrip Google Ads menawarkan dukungan untuk mutasi generik yang tersedia di
Google Ads API. Sebagian besar operasi yang dapat dilakukan
dari GoogleAdsService.mutate
juga dapat
dilakukan dalam skrip Google Ads, termasuk membuat dan mengelola kampanye.
Karena fitur ini memungkinkan akses ke sebagian besar Google Ads API, penting untuk memiliki pemahaman dasar tentang konvensi Google Ads API agar dapat menggunakan fitur ini. Banyak aspek yang dapat dilewati, seperti token developer dan otorisasi, karena aspek tersebut ditangani oleh skrip Google Ads, tetapi Anda harus membuat permintaan mutasi yang valid.
Berikut beberapa referensi dasar tentang antarmuka REST Google Ads API yang harus Anda ketahui sebelum melanjutkan panduan ini:
Contoh dasar
Untuk menunjukkan fungsi tersebut, perhatikan contoh dasar berikut yang membuat anggaran kampanye:
const budgetResult = AdsApp.mutate({
campaignBudgetOperation: {
create: {
amountMicros: 10000000,
explicitlyShared: false
}
}
});
Panggilan ke AdsApp.mutate
akan mengambil objek JSON yang mewakili satu MutateOperation
. Dalam objek ini, Anda
menentukan jenis operasi yang Anda lakukan—dalam hal ini, campaignBudgetOperation
. Kemudian, tentukan create
, remove
, atau
update
dan updateMask
. Kolom spesifik dalam create
dan update
bergantung pada jenis resource tertentu yang Anda gunakan.
Membuat operasi
Ada beberapa strategi yang dapat Anda gunakan untuk membuat operasi yang valid. Tetap menggunakan contoh anggaran kampanye, Anda dapat mencari dokumentasi referensi REST untuk anggaran kampanye untuk melihat daftar semua kolom yang valid, lalu mengisi kolom yang sesuai, atau menulis kode JavaScript kustom dalam skrip untuk membuat objek yang tepat.
Atau, Anda dapat mencoba membuat operasi secara dinamis menggunakan fitur"Coba ini" untuk anggaran kampanye, yang memungkinkan Anda membuat isi permintaan secara dinamis dengan memilih dan memilih kolom yang ingin ditambahkan.
Selanjutnya, Anda dapat mengekstrak isi operasi dari hasil yang dihasilkan dan menambahkannya ke panggilan mutate
setelah menentukan jenis operasi.
Jenis-jenis operasi
Buat
Tentukan create
dalam operasi Anda, dengan meneruskan representasi ulang objek dari
resource yang ingin Anda buat.
Lihat contoh operasi create
di atas.
Hapus
Tentukan remove
dalam operasi Anda, dengan meneruskan nama
resource resource yang ingin
dihapus, misalnya:
AdsApp.mutate({
adGroupOperation: {
remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
}
});
Jika tidak mengetahui nama resource untuk entity, Anda dapat mengambilnya
menggunakan
permintaan
Adsapp.search
.
Update
Tentukan update
dalam operasi Anda, dengan meneruskan objek dengan nama resource
yang ditentukan sehingga sistem dapat menentukan objek yang ingin
Anda update. Selain itu, isi kolom yang ingin Anda perbarui nilainya, dan tentukan updateMask
yang menunjukkan kolom mana yang ingin Anda ubah dalam permintaan ini. Jangan menyertakan nama resource dalam
mask update.
Contoh operasi update
:
const campaignResult = AdsApp.mutate({
campaignOperation: {
update: {
resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
status: "PAUSED",
name: "[Paused] My campaign"
},
updateMask: "name,status"
}
});
Menangani hasil
Apa pun jenis operasinya, nilai yang ditampilkan adalah
MutateResult
.
Anda dapat menggunakan nama resource yang ditampilkan untuk mengkueri status resource saat ini
setelah mutasi, dan memeriksa apakah operasi berhasil atau
error apa yang terjadi jika ada.
Berikut adalah contoh yang menunjukkan alur dasar untuk memeriksa hasil dan mencetak beberapa informasi ke log:
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);
}
}
Beberapa operasi
Skrip Google Ads juga mendukung mutasi beberapa operasi dalam satu permintaan dengan metode AdsApp.mutateAll
. Anda dapat membuat entitas yang bergantung satu sama lain, seperti hierarki kampanye lengkap dalam satu permintaan. Secara opsional, Anda dapat membuat seluruh rangkaian operasi menjadi atomik, sehingga jika ada yang gagal, tidak ada yang akan dijalankan.
Nilai yang ditampilkan adalah array objek MutateResult
, satu untuk setiap operasi yang Anda berikan dan dalam urutan yang sama seperti operasi awal.
Fitur ini berfungsi sama seperti fitur Google Ads API. Jadi, baca panduan praktik terbaik Google Ads API untuk mendapatkan penjelasan lengkap tentang ID sementara dan pertimbangan lainnya. Perhatikan bahwa panduan ini menggunakan snake_case
untuk mewakili nama kolom, sedangkan dokumentasi skrip Google Ads menggunakan lowerCamelCase
. Kedua kasus ini diterima dalam skrip Google Ads, sehingga Anda dapat menyalin kode langsung dari panduan tersebut.
Untuk membuat beberapa operasi dalam satu permintaan, kumpulkan semua operasi Anda ke dalam array, lalu panggil AdsApp.mutateAll
. Panggilan mutateAll
menggunakan array operasi sebagai argumen pertama dan argumen kedua opsional dari opsi, termasuk:
apiVersion
: Anda dapat menentukan versi API kustom, sepertiV16
, jika ingin menggunakan versi selain default skrip. Anda dapat menggunakan versi yang tersedia secara publik pada saat itu.partialFailure
: Kolom ini ditetapkan secara default ketrue
. Jika ditetapkan ketrue
, operasi yang valid akan dilakukan dan operasi yang gagal akan menampilkan error. Jika ditetapkan kefalse
, maka jika ada operasi yang gagal, tidak ada operasi yang akan dijalankan, sehingga kumpulan operasi ini akan menjadi atomik.
Berikut ini contoh dengan beberapa operasi yang membuat anggaran kampanye, kampanye, dan grup iklan dalam permintaan atomik.
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});