Mask kolom

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

Utilitas FieldMasks

Cara yang direkomendasikan untuk membuat mask kolom di library klien Java adalah dengan menggunakan class utilitas FieldMasks bawaan, yang memungkinkan Anda membuat mask kolom 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.

Kemudian, contoh memanggil FieldMasks.allSetFieldsOf() di kampanye untuk membuat mask kolom secara otomatis yang mencantumkan 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 mask kolom dari awal, buat builder FieldMask dan tambahkan nama snake_case setiap kolom yang ingin Anda ubah:

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

Memperbarui kolom pesan dan sub-kolomnya

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 sub-kolom yang ditentukan

Saat memperbarui kolom MESSAGE yang telah menentukan sub-kolom tanpa menetapkan sub-kolom apa pun secara eksplisit pada pesan tersebut, Anda harus menambahkan setiap sub-kolom 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 mengupdate kampanye untuk menggunakan strategi bidding MaximizeConversions tanpa menetapkan sub-bidang apa pun pada strategi bidding.

Dalam hal ini, penggunaan metode allSetFieldsOf() dan compare() untuk FieldMasks saja tidak mencapai tujuan yang diinginkan.

Contoh berikut menghasilkan mask kolom yang mencakup maximize_conversions. Namun, Google Ads API tidak mengizinkan jalur pesan level teratas yang memiliki sub-kolom dalam mask update (untuk mencegah sub-kolom dihapus secara tidak sengaja) dan menampilkan 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 subfield-nya. Pelajari lebih lanjut cara menetapkan strategi bidding standar dan portofolio.

// 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. Mirip dengan contoh sebelumnya, Anda harus menambahkan kolom ini secara eksplisit ke mask kolom sambil membiarkannya tidak ditetapkan pada objek pesan. Misalnya, anggaplah 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 seperti yang dimaksud:

// 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.

// 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();