Method: customers.googleAds.mutate

Membuat, memperbarui, atau menghapus resource. Metode ini mendukung transaksi atomik dengan beberapa jenis resource. Misalnya, Anda dapat membuat kampanye dan anggaran kampanye secara otomatis, atau melakukan hingga ribuan mutasi secara otomatis.

Pada dasarnya, metode ini adalah wrapper untuk serangkaian metode mutasi. Satu-satunya fitur yang ditawarkan dibandingkan dengan memanggil metode tersebut secara langsung adalah:

  • Transaksi atomik
  • Nama resource sementara (dijelaskan di bawah)
  • Mengurangi latensi saat membuat serangkaian panggilan mutasi

Catatan: Hanya resource yang mendukung transaksi atomik yang disertakan, sehingga metode ini tidak dapat menggantikan semua panggilan ke setiap layanan.

Manfaat Transaksi Atomik

Atomitas membuat penanganan error menjadi jauh lebih mudah. Jika Anda membuat serangkaian perubahan dan salah satunya gagal, akun Anda dapat berada dalam status yang tidak konsisten. Dengan atomitas, Anda akan mencapai status yang dipilih secara langsung, atau permintaan akan gagal dan Anda dapat mencoba lagi.

Nama Resource Sementara

Nama resource sementara adalah jenis nama resource khusus yang digunakan untuk membuat resource dan mereferensikan resource tersebut dalam permintaan yang sama. Misalnya, jika anggaran kampanye dibuat dengan resourceName sama dengan customers/123/campaignBudgets/-1, nama resource tersebut dapat digunakan kembali di kolom Campaign.budget dalam permintaan yang sama. Dengan begitu, kedua resource dibuat dan ditautkan secara atomik.

Untuk membuat nama resource sementara, masukkan angka negatif di bagian nama yang biasanya dialokasikan server.

Catatan:

  • Resource harus dibuat dengan nama sementara sebelum nama tersebut dapat digunakan kembali. Misalnya, contoh CampaignBudget+Campaign sebelumnya akan gagal jika urutan mutasi dibalik.
  • Nama sementara tidak diingat di seluruh permintaan.
  • Tidak ada batasan jumlah nama sementara dalam permintaan.
  • Setiap nama sementara harus menggunakan angka negatif unik, meskipun jenis resource berbeda.

Latensi

Anda harus mengelompokkan mutasi menurut jenis resource atau permintaan mungkin akan habis waktunya dan gagal. Latensi kira-kira sama dengan serangkaian panggilan ke setiap metode mutasi, dengan setiap perubahan jenis resource adalah panggilan baru. Misalnya, memutasi 10 kampanye, lalu 10 grup iklan sama dengan 2 panggilan, sedangkan memutasi 1 kampanye, 1 grup iklan, 1 kampanye, 1 grup iklan sama dengan 4 panggilan.

Daftar error yang ditampilkan: AdCustomizerError AdError AdGroupAdError AdGroupCriterionError AdGroupError AssetError AuthenticationError AuthorizationError BiddingError CampaignBudgetError CampaignCriterionError CampaignError CampaignExperimentError CampaignSharedSetError CollectionSizeError ContextError ConversionActionError CriterionError CustomerFeedError DatabaseError DateError DateRangeError DistinctError ExtensionFeedItemError ExtensionSettingError FeedAttributeReferenceError FeedError FeedItemError FeedItemSetError FieldError FieldMaskError FunctionParsingError HeaderError ImageError InternalError KeywordPlanAdGroupKeywordError KeywordPlanCampaignError KeywordPlanError LabelError ListOperationError MediaUploadError MutateError NewResourceCreationError NullError OperationAccessDeniedError PolicyFindingError PolicyViolationError QuotaError RangeError RequestError ResourceCountLimitExceededError SettingError SharedSetError SizeLimitError StringFormatError StringLengthError UrlFieldError UserListError YoutubeVideoRegistrationError

Permintaan HTTP

POST https://googleads.googleapis.com/v19/customers/{customerId}/googleAds:mutate

URL menggunakan sintaksis gRPC Transcoding.

Parameter jalur

Parameter
customerId

string

Wajib. ID pelanggan yang resource-nya sedang diubah.

Isi permintaan

Isi permintaan memuat data dengan struktur berikut:

Representasi JSON 
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
Kolom
mutateOperations[]

object (MutateOperation)

Wajib. Daftar operasi yang akan dilakukan pada setiap resource.
partialFailure

boolean

Jika benar, operasi yang berhasil akan dilakukan dan operasi yang tidak valid akan menampilkan error. Jika salah, semua operasi akan dilakukan dalam satu transaksi jika dan hanya jika semuanya valid. Defaultnya adalah false.
validateOnly

boolean

Jika benar, permintaan divalidasi tetapi tidak dieksekusi. Hanya error yang ditampilkan, bukan hasil.
responseContentType

enum (ResponseContentType)

Setelan jenis konten respons. Menentukan apakah resource yang dapat diubah atau hanya nama resource yang akan ditampilkan setelah mutasi. Resource yang dapat diubah hanya akan ditampilkan jika resource memiliki kolom respons yang sesuai. Misalnya, MutateCampaignResult.campaign.

Isi respons

Pesan respons untuk GoogleAdsService.Mutate.

Jika berhasil, isi respons memuat data dengan struktur berikut:

Representasi JSON 
{
  "partialFailureError": {
    object (Status)
  },
  "mutateOperationResponses": [
    {
      object (MutateOperationResponse)
    }
  ]
}
Kolom
partialFailureError

object (Status)

Error yang berkaitan dengan kegagalan operasi dalam mode kegagalan sebagian. Hanya ditampilkan jika partialFailure = true dan semua error terjadi di dalam operasi. Jika terjadi error di luar operasi (misalnya, error autentikasi), kami akan menampilkan error tingkat RPC.
mutateOperationResponses[]

object (MutateOperationResponse)

Semua respons untuk mutasi.

Cakupan otorisasi

Memerlukan cakupan OAuth berikut:

  • https://www.googleapis.com/auth/adwords

Untuk mengetahui informasi selengkapnya, lihat OAuth 2.0 Overview.