Mutasi

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 di skrip Google Ads, termasuk membuat dan mengelola kampanye.

Karena fitur ini memungkinkan akses ke sebagian besar Google Ads API, Anda harus memahami konvensi dasar Google Ads API untuk menggunakan fitur ini. Banyak aspek yang dapat dilewati, seperti token developer dan otorisasi, karena aspek tersebut ditangani untuk Anda oleh skrip Google Ads, tetapi Anda harus membuat permintaan perubahan yang valid.

Berikut beberapa referensi dasar tentang antarmuka REST Google Ads API yang harus Anda pahami sebelum melanjutkan panduan ini:

Contoh dasar

Untuk mendemonstrasikan fungsi, perhatikan 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 merepresentasikan satu MutateOperation. Dalam objek ini, Anda menentukan jenis operasi yang Anda lakukan—dalam hal ini, campaignBudgetOperation. Kemudian, Anda menentukan create, remove, atau keduanya 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 membangun operasi yang valid. Dengan contoh anggaran kampanye, Anda dapat mencari dokumentasi referensi REST untuk anggaran kampanye guna melihat daftar semua kolom validnya, lalu mengisi kolom yang sesuai, atau menulis kode JavaScript kustom dalam skrip Anda 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 Anda tambahkan. 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 dari resource yang ingin Anda hapus, misalnya:

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

Jika Anda tidak mengetahui nama resource untuk suatu entitas, Anda dapat mengambilnya menggunakan permintaan Adsapp.search.

Perbarui

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

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 lihat panduan praktik terbaik Google Ads API untuk penjelasan lengkap tentang ID sementara dan pertimbangan lainnya; perhatikan bahwa panduan ini menggunakan snake_case untuk merepresentasikan 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 melakukan 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, seperti V20, jika ingin menggunakan versi selain default skrip. Anda dapat menggunakan versi yang tersedia secara publik pada saat itu.
  • partialFailure: Kolom ini secara default adalah true. Jika disetel ke true, maka operasi yang valid akan dilakukan dan operasi yang gagal akan menampilkan error. Jika disetel ke false, jika ada operasi yang gagal, tidak ada operasi yang dilakukan, sehingga efektif membuat kumpulan operasi ini bersifat atomik.

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