Layanan resource berubah

Menggunakan layanan khusus resource adalah cara paling langsung untuk membuat, memperbarui, atau menghapus entitas dari satu jenis resource di Google Ads API.

Endpoint perubahan

Setiap resource yang dapat diubah memiliki jenis layanan dan operasi yang sesuai. Untuk mengubah resource menggunakan layanan khusus, isi salah satu kolom berikut pada operasi dan kirimkan ke endpoint perubahan layanan:

• Buat (create): Objek resource baru yang akan dibuat.
• Update (update): Objek resource yang diubah, disertai dengan update_mask yang menentukan kolom yang diubah.
• Hapus (remove): String resource_name dari resource target yang akan dihapus.

Misalnya, untuk membuat Campaign baru, selesaikan langkah-langkah berikut:

1. Buat objek Campaign dengan atribut yang Anda pilih.
2. Tetapkan ke kolom create dari CampaignOperation.
3. Kirim operasi dalam MutateCampaignsRequest ke CampaignService.MutateCampaigns.

Pola yang sama ini berlaku di semua layanan khusus resource di Google Ads API:

• AdGroup: Teruskan AdGroupOperation ke AdGroupService.MutateAdGroups.
• CampaignCriterion: Teruskan CampaignCriterionOperation ke CampaignCriterionService.MutateCampaignCriteria.

Payload JSON REST berikut menggambarkan permintaan ke CampaignService.MutateCampaigns:

{
  "customerId": "CUSTOMER_ID",
  "operations": [
    {
      "create": {
        "name": "Interplanetary Cruise #1",
        "advertisingChannelType": "SEARCH",
        "status": "PAUSED",
        "manualCpc": {},
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/BUDGET_ID",
        "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING"
      }
    }
  ],
  "partialFailure": false,
  "validateOnly": false
}

Beberapa operasi dan batasan

Karena kolom operations dari permintaan modifikasi berulang, satu permintaan dapat berisi beberapa operasi (hingga 10.000 operasi per permintaan) untuk jenis resource tersebut. Secara default, semua operasi dalam permintaan dijalankan secara atomik kecuali jika Anda menyetel partial_failure ke true.

Namun, layanan resource individual memiliki dua batasan penting:

• Satu jenis resource: Permintaan ke layanan resource hanya dapat mengubah resource yang dikelola oleh layanan tertentu tersebut.
• Tidak ada ID resource sementara atau referensi silang: Operasi dalam panggilan mutasi khusus resource diproses secara independen. Anda tidak dapat menetapkan ID negatif sementara (seperti customers/CUSTOMER_ID/campaigns/-1) atau merujuk entitas yang baru dibuat dari operasi lain dalam permintaan yang sama.

Jika Anda perlu mengubah beberapa jenis resource dalam satu permintaan atau merujuk nama resource sementara di seluruh operasi yang bergantung, gunakan GoogleAdsService.Mutate.

Perbedaan khusus versi

Perhatikan perbedaan berikut di seluruh versi Google Ads API yang didukung saat mengubah resource:

• Layanan sasaran siklus proses: Di v25 dan yang lebih baru, semua sasaran siklus proses—termasuk Akuisisi Pelanggan Baru (new_customer_acquisition_goal_settings), Retensi Pelanggan (retention_goal_settings), dan Retensi Loyalitas (loyalty_retention_goal_settings)—dimutasi melalui GoalService.MutateGoals dan CampaignGoalConfigService.MutateCampaignGoalConfigs menggunakan kolom operations berulang standar. Hal ini menggantikan CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals dan CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals (yang digunakan untuk Akuisisi Pelanggan Baru di v24 dan yang lebih lama serta menerima kolom operation tunggal).
• Kolom tanggal dan waktu kampanye: Saat membuat atau memperbarui Campaign, v23 dan yang lebih baru menggunakan start_date_time dan end_date_time (yyyy-MM-dd HH:mm:ss), menggantikan kolom start_date dan end_date hanya tanggal yang digunakan di v22.
• Mutabilitas pengesahan konten sintetis: Meskipun Asset.synthetic_content_info dan Ad.synthetic_content_info muncul dalam skema untuk v22 dan yang lebih baru, kolom synthetic_content_info.advertiser_attestation.status dan synthetic_content_info.advertiser_attestation.source hanya dapat diubah di v23 dan yang lebih baru (system_attestation selalu OUTPUT_ONLY). Mencoba mengubah sub-kolom advertiser_attestation di v22 akan menampilkan error kolom tidak dapat diubah ("The field attempted to be mutated is immutable" atau "Field cannot be set").