Menggunakan ID sementara

Nama resource sementara

BatchJobService mendukung nama resource sementara yang dapat dirujuk dalam operasi berikutnya dalam tugas batch yang sama—termasuk di beberapa permintaan AddBatchJobOperations berurutan yang diupload dengan sequence_token. Dengan demikian, Anda dapat membuat kampanye dan grup iklan, iklan, serta kriteria yang bergantung padanya dalam satu tugas batch sebelum ID sisi server ditetapkan. Dalam aturan umum dan contoh berikut, satu permintaan mengacu pada seluruh BatchJob di semua upload AddBatchJobOperations-nya.

Untuk mereferensikan resource yang baru dibuat dalam permintaan modifikasi atau tugas batch yang sama, tentukan ID bilangan bulat negatif (seperti -1 atau -2, tidak termasuk 0) di kolom resource_name resource baru. Misalnya, saat membuat kampanye dalam permintaan batch, tetapkan nama resource-nya ke customers/CUSTOMER_ID/campaigns/-1. Saat membuat grup iklan dalam operasi berikutnya dalam permintaan yang sama, referensikan customers/CUSTOMER_ID/campaigns/-1 sebagai kampanye induk. API akan otomatis mengganti -1 dengan ID kampanye sebenarnya yang dibuat saat pembuatan.

Batasan penggunaan

Perhatikan aturan berikut saat menggunakan nama resource sementara:

• Urutan itu penting: Anda hanya dapat mereferensikan nama resource sementara setelah menentukannya. Dalam daftar operasi, operasi dependen (seperti membuat grup iklan) harus muncul setelah operasi yang membuat resource induknya (seperti membuat kampanye).
• Cakupan permintaan tunggal atau tugas batch: Nama resource sementara tidak bertahan di seluruh tugas atau permintaan modifikasi yang terpisah. Untuk mereferensikan resource yang dibuat dalam tugas atau permintaan modifikasi sebelumnya, gunakan nama resource yang sebenarnya yang dibuat oleh sistem.
• Keunikan global: Dalam satu tugas atau permintaan modifikasi, setiap nama resource sementara harus menggunakan bilangan bulat negatif yang unik di semua jenis resource. Misalnya, Anda tidak dapat menetapkan -1 ke kampanye dan grup iklan dalam permintaan yang sama. Menggunakan kembali ID sementara dalam permintaan atau tugas batch yang sama akan menampilkan error NewResourceCreationError.DUPLICATE_TEMP_IDS.

Contoh payload

Misalnya, Anda ingin menambahkan kampanye, grup iklan, dan iklan dalam satu permintaan API atau tugas batch. Anda dapat menyusun array mutateOperations dalam payload permintaan GoogleAdsService.Mutate atau BatchJobService.AddBatchJobOperations seperti yang ditunjukkan dalam contoh JSON REST berikut (dengan kolom resource wajib lainnya dihilangkan agar lebih singkat):

{
  "mutateOperations": [
    {
      "campaignOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/adGroups/-2",
          "campaign": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupAdOperation": {
        "create": {
          "adGroup": "customers/CUSTOMER_ID/adGroups/-2"
        }
      }
    }
  ]
}

Contoh ini menunjukkan detail penting berikut:

• Grup iklan menggunakan ID sementara baru (-2) karena -1 sudah ditetapkan ke kampanye.
• Grup iklan mereferensikan customers/CUSTOMER_ID/campaigns/-1 untuk menautkan dirinya ke kampanye yang dibuat dalam operasi sebelumnya.
• adGroupAdOperation mereferensikan customers/CUSTOMER_ID/adGroups/-2 dan menghilangkan resourceName karena tidak ada operasi berikutnya dalam permintaan yang mereferensikan iklan baru.

Penanganan error dalam tugas batch

Karena operasi standar dalam tugas batch dijalankan dengan kegagalan parsial diaktifkan (kecuali dalam sub-batch atomik), jika resource induk dengan ID sementara gagal divalidasi, setiap operasi turunan dependen yang merujuk ke ID sementara tersebut akan gagal dengan NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. Menggunakan kembali ID negatif yang sama di beberapa operasi create dalam tugas batch yang sama akan menampilkan NewResourceCreationError.DUPLICATE_TEMP_IDS. ID sementara hanya valid saat membuat resource (create) atau mereferensikan resource induk yang baru dibuat; misalnya, meneruskan ID sementara negatif di AdGroupCriterionOperation.remove saat memanggil AddBatchJobOperations akan menampilkan RequestError.RESOURCE_NAME_MALFORMED.