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 memiliki pemahaman dasar tentang konvensi 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 modifikasi yang valid.

Berikut beberapa referensi dasar tentang antarmuka REST Google Ads API yang harus Anda pahami 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, Anda menentukan 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 dan menentukan 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 dari resource yang ingin Anda buat.

Lihat cuplikan yang diberikan sebelumnya 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 tidak mengetahui nama resource untuk suatu entity, Anda dapat mengambilnya menggunakan permintaan Adsapp.search.

Perbarui

Tentukan update dalam operasi Anda, dengan meneruskan objek yang nama resource-nya telah ditentukan agar 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

Terlepas dari 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 set operasi menjadi atomik, sehingga jika ada satu yang gagal, tidak ada yang akan 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 mewakili nama kolom, sedangkan dokumentasi skrip Google Ads menggunakan lowerCamelCase. Kedua kasus ini diterima di 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 V26, jika ingin menggunakan versi selain default skrip. Anda dapat menggunakan versi apa pun yang tersedia untuk umum 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 set operasi ini menjadi 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});