Mutasi

Catatan: Lihat bagian Mutates dari contoh yang menyertainya untuk mengetahui contoh yang lebih lengkap.

Sebagian besar resource diubah (dibuat, diperbarui, atau dihapus) menggunakan metode Mutate. Metode Mutate dipanggil sebagai POST HTTP ke URL khusus resource yang cocok dengan pola nama resource, tanpa ID resource di akhir. ID resource yang akan diubah dikirim dalam isi permintaan JSON. Dengan begitu, Anda dapat mengirim satu panggilan API yang berisi beberapa operasi pada resource yang berbeda.

Misalnya, nama resource kampanye menggunakan format berikut:

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

Untuk mendapatkan URL yang digunakan untuk mengubah kampanye, hapus ID resource di akhir dan tambahkan :mutate:

https://googleads.googleapis.com/v19/customers/CUSTOMER_ID/campaigns:mutate

Pesan Mutate berisi objek JSON tingkat atas dengan array operations yang dapat berisi banyak objek operation. Setiap operasi, pada gilirannya, dapat berupa salah satu dari: create, update, atau remove. Ini adalah satu-satunya operasi mutasi yang mungkin.

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    ...
  ]
}

Sebagian besar layanan mendukung ribuan operasi dalam satu panggilan API. Panduan Batas Sistem mendokumentasikan batasan pada ukuran permintaan.

Operasi dalam satu permintaan API dijalankan sebagai satu kumpulan tindakan secara default, yang berarti semuanya berhasil bersama-sama atau seluruh batch gagal jika satu operasi gagal. Beberapa layanan mendukung atribut partialFailure untuk mengubah perilaku ini. Lihat Mengubah Resource untuk mengetahui informasi selengkapnya tentang semantik operasi ubah.

Buat

Operasi pembuatan menghasilkan entitas baru dan harus menyertakan representasi JSON lengkap dari resource yang ingin Anda buat.

Poin Penting: Operasi Create tidak menentukan resourceName atau ID. Jika panggilan API berhasil, respons akan menyertakan resourceName yang dihasilkan untuk objek yang baru dibuat.

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
    "create": {
        "name": "An example campaign",
        "status": "PAUSED",
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/CAMPAIGN_BUDGET_ID",
        "advertisingChannelType": "SEARCH",
        "networkSettings": {
          "targetGoogleSearch": true,
          "targetSearchNetwork": true,
          "targetContentNetwork": true,
          "targetPartnerSearchNetwork": false
        },
        "target_spend": {}
      }
    }
  ]
}

Perbarui

Operasi update melakukan update jarang ke resource yang ada. Anda hanya perlu menentukan kolom yang ingin diubah.

Untuk menentukan kolom yang ingin Anda perbarui, tetapkan atribut updateMask ke daftar nama kolom yang dipisahkan koma. Hal ini sangat berguna jika Anda sudah memiliki representasi JSON objek yang terbentuk sepenuhnya (misalnya, seperti yang ditampilkan oleh panggilan API sebelumnya), tetapi hanya ingin mengubah kolom tertentu. Daripada memangkas objek JSON, Anda cukup mencantumkan nama kolom yang akan diubah di updateMask dan mengirim seluruh objek JSON.

Poin Penting: update_mask adalah kolom standar yang digunakan di seluruh Google API untuk memfasilitasi pelaksanaan update sebagian pada resource tertentu. Lihat dokumentasi referensi FieldMask untuk mengetahui detail lengkapnya.

Contoh di bawah mengubah name dan status kampanye yang ada yang memiliki resourceName tertentu.

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
      "updateMask": "name,status",
      "update": {
        "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID",
        "name": "My renamed campaign",
        "status": "PAUSED",
      }
    }
  ]
}

Hapus

Operasi penghapusan akan menghapus objek secara efektif, dengan menetapkan status Google Ads-nya ke REMOVED. Hanya resourceName yang akan dihapus yang diperlukan.

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
      "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID"
    }
  ]
}