Mutasi

Skrip Google Ads menawarkan dukungan untuk mutasi umum 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, Anda harus memiliki pemahaman dasar tentang konvensi Google Ads API untuk menggunakan fitur ini. Banyak aspek yang dapat dilewati, seperti token developer dan otorisasi, karena hal tersebut ditangani untuk Anda 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 fungsinya, pertimbangkan contoh dasar ini yang membuat anggaran kampanye:

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

Panggilan ke AdsApp.mutate mengambil objek JSON yang mewakili satu MutateOperation. Dalam objek ini, tentukan jenis operasi yang Anda lakukan—dalam hal ini, campaignBudgetOperation. Kemudian, Anda menentukan create, remove, atau update dan updateMask. Kolom tertentu dalam create dan update bergantung pada jenis resource tertentu yang Anda operasikan.

Membangun operasi

Ada beberapa strategi yang dapat Anda gunakan untuk membuat operasi yang valid. Dengan tetap menggunakan contoh anggaran kampanye, Anda dapat mencari dokumentasi referensi REST untuk anggaran kampanye guna melihat daftar semua kolom yang valid, lalu mengisi kolom yang sesuai, atau menulis kode JavaScript kustom dalam skrip untuk membuat objek yang sesuai.

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 kolom yang ingin ditambahkan. Kemudian, Anda dapat mengekstrak konten 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 objek resource yang ingin Anda buat.

Lihat di atas untuk contoh operasi create.

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 suatu entity, Anda dapat mengambilnya menggunakan permintaan Adsapp.search.

Perbarui

Tentukan update dalam operasi Anda, dengan meneruskan objek dengan nama resource yang ditentukan sehingga sistem dapat menentukan objek mana yang ingin Anda update. Selain itu, isi kolom yang ingin Anda perbarui nilainya, dan tentukan updateMask yang menunjukkan dengan tepat kolom yang ingin Anda ubah dalam permintaan ini. Jangan sertakan 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 membuat kueri 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 entity yang saling bergantung, seperti hierarki kampanye lengkap dalam satu permintaan. Secara opsional, Anda dapat membuat seluruh kumpulan operasi menjadi atomik, sehingga jika ada yang gagal, tidak ada yang dijalankan.

Nilai yang ditampilkan adalah array objek MutateResult, satu untuk setiap operasi yang Anda berikan dan dalam urutan yang sama dengan 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 menampilkan 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 ke dalam array, lalu panggil AdsApp.mutateAll. Panggilan mutateAll menggunakan array operasi sebagai argumen pertama dan argumen opsi kedua yang opsional, termasuk:

  • apiVersion: Anda dapat menentukan versi API kustom, seperti V18, jika ingin menggunakan versi selain default skrip. Anda dapat menggunakan versi apa pun yang tersedia secara publik pada saat itu.
  • partialFailure: Kolom ini ditetapkan secara default ke true. Jika ditetapkan ke true, operasi yang valid akan dilakukan dan operasi yang gagal akan menampilkan error. Jika ditetapkan ke false, jika ada operasi yang gagal, tidak ada operasi yang dilakukan, sehingga kumpulan operasi ini menjadi atomik secara efektif.

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