Mask kolom

Di Google Ads API, pembaruan dilakukan menggunakan masker kolom. Masker kolom (google.protobuf.FieldMask) berisi daftar jalur kolom di snake_case yang ingin Anda ubah dengan update. Setiap kolom yang ditentukan yang tidak ada dalam mask kolom akan diabaikan, meskipun dikirim ke server.

Utilitas FieldMasks

Cara yang direkomendasikan untuk membuat field mask di library klien Java adalah menggunakan class utilitas FieldMasks bawaan, yang memungkinkan Anda membuat field mask dari objek yang diubah, bukan membuatnya dari awal.

Berikut contoh untuk memperbarui kampanye:

// Creates a Campaign object with the proper resource name and any other
// changes.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation that updates the campaign, using the
// FieldMasks.allSetFieldsOf utility to derive the update mask. This mask tells
// the Google Ads API which attributes of the campaign you want to change.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

Contoh ini pertama-tama membuat builder Campaign kosong dan menetapkan nama resource-nya sehingga API mengetahui kampanye mana yang sedang diperbarui.

Contoh ini kemudian memanggil FieldMasks.allSetFieldsOf() pada kampanye untuk otomatis menghasilkan masker kolom yang menghitung semua kolom yang ditetapkan. Anda dapat meneruskan masker yang ditampilkan langsung ke panggilan update.

Jika Anda perlu menggunakan objek yang ada dan memperbarui beberapa kolom, gunakan FieldMasks.compare() sebagai berikut:

// Assumes existingCampaign was retrieved from a previous API call.

// Creates a new campaign based on the existing campaign and updates the
// campaign by setting its status to paused.
Campaign campaignToUpdate =
    existingCampaign.toBuilder()
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation that updates the campaign, using the
// FieldMasks.compare utility to derive the update mask. This mask tells the
// Google Ads API which attributes of the campaign you want to change.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaignToUpdate)
        .setUpdateMask(FieldMasks.compare(existingCampaign, campaignToUpdate))
        .build();

// Sends the operation in a mutate request.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

Untuk membuat field mask dari awal, buat builder FieldMask dan tambahkan nama snake_case dari setiap kolom yang ingin Anda ubah:

FieldMask fieldMask =
    FieldMask.newBuilder()
        .addPaths("status")
        .addPaths("name")
        .build();

Memperbarui kolom pesan dan subkolomnya

Kolom MESSAGE dapat memiliki subkolom (seperti MaximizeConversions, yang memiliki target_cpa_micros, cpc_bid_ceiling_micros, dan cpc_bid_floor_micros), atau tidak memiliki subkolom (seperti ManualCpm).

Kolom pesan tanpa subkolom yang ditentukan

Saat memperbarui kolom MESSAGE yang tidak ditentukan dengan subkolom apa pun, gunakan utilitas FieldMasks untuk membuat mask kolom, seperti yang dijelaskan di bagian sebelumnya.

Kolom pesan dengan subkolom yang ditentukan

Saat memperbarui kolom MESSAGE yang telah menentukan subkolom tanpa menetapkan subkolom apa pun secara eksplisit pada pesan tersebut, Anda harus menambahkan setiap subkolom MESSAGE yang dapat diubah ke FieldMask secara manual, mirip dengan membuat mask kolom dari awal.

Salah satu contoh umum adalah memperbarui strategi bidding kampanye (kolom oneof campaign_bidding_strategy) tanpa menetapkan kolom apa pun pada strategi bidding baru. Contoh berikut menunjukkan cara memperbarui kampanye untuk menggunakan strategi bidding MaximizeConversions tanpa menetapkan subkolom apa pun pada strategi bidding.

Dalam hal ini, menggunakan metode allSetFieldsOf() dan compare() dari FieldMasks saja tidak akan mencapai tujuan yang diinginkan.

Contoh berikut menghasilkan mask kolom yang menyertakan maximize_conversions. Namun, Google Ads API tidak mengizinkan jalur pesan tingkat teratas yang memiliki subkolom dalam update mask (untuk mencegah penghapusan subkolom secara tidak sengaja) dan menampilkan error FieldMaskError.FIELD_HAS_SUBFIELDS.

Peringatan: Kode berikut menghasilkan error FieldMaskError.FIELD_HAS_SUBFIELDS.

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setMaximizeConversions(MaximizeConversions.newBuilder().build())
        .build();

// Constructs an operation using FieldMasks.allSetFieldsOf to derive the update
// mask. The field mask includes 'maximize_conversions', which produces a
// FieldMaskError.FIELD_HAS_SUBFIELDS error.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request that results in a
// FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields with
// subfields cannot be included directly in a field mask.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

Contoh berikut menunjukkan cara memperbarui kampanye dengan benar untuk menggunakan strategi bidding MaximizeConversions tanpa menetapkan subkolomnya. Pelajari lebih lanjut cara menetapkan strategi bidding standar dan portofolio.

Berhasil: Kode berikut memperbarui strategi bidding kampanye tanpa error.

// Creates a Campaign object with the proper resource name.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .build();

// Creates a field mask from the campaign and adds the mutable subfield
// ('maximize_conversions.target_cpa_micros') on the MaximizeConversions
// bidding strategy to the field mask. Because this subfield is included in the
// field mask while excluded from the campaign object, the Google Ads API
// switches the campaign's bidding strategy oneof to MaximizeConversions with
// target_cpa_micros unset.
FieldMask fieldMask =
    FieldMasks.allSetFieldsOf(campaign).toBuilder()
        .addPaths("maximize_conversions.target_cpa_micros")
        .build();

// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(fieldMask)
        .build();

Hapus kolom

Beberapa kolom dapat dihapus secara eksplisit. Serupa dengan contoh sebelumnya, Anda harus menambahkan kolom ini secara eksplisit ke mask kolom, tetapi tidak menyetelnya pada objek pesan. Misalnya, Anda memiliki kampanye yang menggunakan strategi bidding MaximizeConversions dan kolom target_cpa_micros ditetapkan dengan nilai yang lebih besar dari 0.

Kode berikut berjalan, tetapi maximize_conversions.target_cpa_micros tidak akan dihapus sebagaimana mestinya:

Peringatan: Kode ini tidak menghapus target_cpa_micros di strategi bidding MaximizeConversions.

// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set to 0L.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setMaximizeConversions(
            MaximizeConversions.newBuilder().setTargetCpaMicros(0L).build())
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation using FieldMasks.allSetFieldsOf to derive the
// update mask.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request that does not clear the field
// cleanly.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

Contoh berikutnya menunjukkan cara menghapus kolom target_cpa_micros dengan benar pada strategi bidding MaximizeConversions.

Berhasil: Kode berikut menghapus target_cpa_micros.

// Creates a Campaign object with the proper resource name.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .build();

// Constructs a field mask from the campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which
// clears this field from the bidding strategy without impacting any other
// fields on the bidding strategy.
FieldMask fieldMask =
    FieldMasks.allSetFieldsOf(campaign).toBuilder()
        .addPaths("maximize_conversions.target_cpa_micros")
        .build();

// Creates an operation to update the campaign with the specified field.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(fieldMask)
        .build();

Poin Penting: Jika Anda ingin menghapus kolom, tambahkan jalur kolom tersebut secara eksplisit ke FieldMask dan biarkan kolom tidak ditetapkan pada objek resource.