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 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, seperti V16, jika ingin menggunakan versi selain default skrip. Anda dapat menggunakan versi 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, 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});