Mặt nạ trường

Trong Google Ads API, các bản cập nhật được thực hiện bằng cách sử dụng mặt nạ trường. Mặt nạ cho trường (google.protobuf.FieldMask) chứa danh sách đường dẫn trường trong snake_case mà bạn dự định thay đổi bằng bản cập nhật. Mọi trường được chỉ định không có trong mặt nạ trường đều sẽ bị bỏ qua, ngay cả khi được gửi đến máy chủ.

Tiện ích FieldMasks

Bạn nên sử dụng lớp tiện ích FieldMasks tích hợp sẵn để tạo mặt nạ trường trong thư viện ứng dụng Java. Lớp này cho phép bạn tạo mặt nạ trường từ một đối tượng đã sửa đổi thay vì tạo mặt nạ trường từ đầu.

Sau đây là ví dụ về cách cập nhật một chiến dịch:

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

Ví dụ này trước tiên sẽ tạo một trình tạo Campaign trống và đặt tên tài nguyên của trình tạo đó để API biết chiến dịch nào đang được cập nhật.

Sau đó, ví dụ này gọi FieldMasks.allSetFieldsOf() trên chiến dịch để tự động tạo một mặt nạ trường liệt kê tất cả các trường được đặt. Bạn có thể truyền trực tiếp mặt nạ được trả về đến lệnh gọi cập nhật.

Nếu bạn cần làm việc với một đối tượng hiện có và cập nhật một số trường, hãy dùng FieldMasks.compare() như sau:

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

Để tạo một mặt nạ trường từ đầu, hãy tạo một trình tạo FieldMask và thêm tên snake_case của từng trường mà bạn dự định thay đổi:

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

Cập nhật các trường thông báo và trường con của chúng

Các trường MESSAGE có thể có các trường phụ (chẳng hạn như MaximizeConversions có target_cpa_micros, cpc_bid_ceiling_micros và cpc_bid_floor_micros) hoặc không có trường phụ (chẳng hạn như ManualCpm).

Trường thông báo không có trường con được xác định

Khi cập nhật một trường MESSAGE không được xác định bằng bất kỳ trường con nào, hãy sử dụng tiện ích FieldMasks để tạo một mặt nạ trường, như mô tả trong phần trước.

Trường thông báo có các trường con được xác định

Khi cập nhật một trường MESSAGE có các trường con đã xác định mà không thiết lập rõ ràng bất kỳ trường con nào trên thông báo đó, bạn phải thêm từng trường con có thể thay đổi MESSAGE vào FieldMask theo cách thủ công, tương tự như việc tạo một mặt nạ trường từ đầu.

Một ví dụ phổ biến là cập nhật chiến lược đặt giá thầu của chiến dịch (trường oneof campaign_bidding_strategy) mà không đặt bất kỳ trường nào trên chiến lược đặt giá thầu mới. Ví dụ sau đây minh hoạ cách cập nhật một chiến dịch để sử dụng chiến lược đặt giá thầu MaximizeConversions mà không đặt bất kỳ trường phụ nào trên chiến lược đặt giá thầu.

Trong trường hợp này, việc chỉ sử dụng các phương thức allSetFieldsOf() và compare() của FieldMasks sẽ không đạt được mục tiêu dự kiến.

Ví dụ sau đây tạo ra một mặt nạ trường bao gồm maximize_conversions. Tuy nhiên, Google Ads API không cho phép các đường dẫn thông báo cấp cao nhất có các trường phụ trong mặt nạ cập nhật (để ngăn việc vô tình xoá các trường phụ) và trả về lỗi FieldMaskError.FIELD_HAS_SUBFIELDS.

Cảnh báo: Mã sau đây sẽ tạo ra lỗi 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));

Ví dụ sau đây minh hoạ cách cập nhật đúng cách một chiến dịch để sử dụng chiến lược đặt giá thầu MaximizeConversions mà không đặt bất kỳ trường phụ nào của chiến lược đó. Tìm hiểu thêm về cách chỉ định chiến lược đặt giá thầu tiêu chuẩn và chiến lược giá thầu danh mục đầu tư.

Thành công: Mã sau đây sẽ cập nhật chiến lược đặt giá thầu của chiến dịch mà không gặp lỗi.

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

Xoá các trường

Bạn có thể xoá một số trường một cách rõ ràng. Tương tự như ví dụ trước, bạn phải thêm rõ ràng các trường này vào mặt nạ trường trong khi để trống các trường đó trên đối tượng thông báo. Ví dụ: giả sử bạn có một chiến dịch sử dụng chiến lược đặt giá thầu MaximizeConversions và trường target_cpa_micros được đặt với giá trị lớn hơn 0.

Mã sau đây sẽ chạy, nhưng maximize_conversions.target_cpa_micros sẽ không được xoá như dự kiến:

Cảnh báo: Mã này không xoá target_cpa_micros trên chiến lược đặt giá thầu 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));

Ví dụ tiếp theo minh hoạ cách xoá đúng trường target_cpa_micros trên chiến lược đặt giá thầu MaximizeConversions.

Thành công: Mã sau sẽ xoá 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();

Lưu ý quan trọng: Nếu bạn muốn xoá một trường, hãy thêm đường dẫn của trường đó một cách rõ ràng vào FieldMask và để trường đó không được đặt trên đối tượng tài nguyên.