Mặt nạ trường

Trong Google Ads API, các bản cập nhật được thực hiện bằng mặt nạ trường. Mặt nạ cho trường (google.protobuf.FieldMask) chứa danh sách các đườ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 bị bỏ qua, ngay cả khi được gửi đến máy chủ.

Tiện ích FieldMasks

Bạn nên tạo mặt nạ trường trong thư viện ứng dụng Java bằng cách sử dụng lớp tiện ích FieldMasks tích hợp sẵn. 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 từ đầu.

Dưới đây là ví dụ về cách cập nhậ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 đã đặt. Bạn có thể truyền trực tiếp mặt nạ được trả về vào 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 vài trường, hãy sử 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 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 đị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ó 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 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 đã xác định các trường con mà không đặt rõ ràng bất kỳ trường con nào trong thông báo đó, bạn phải thêm từng trường con MESSAGE có thể thay đổi vào FieldMask theo cách thủ công, tương tự như việc tạo 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) mà không đặt bất kỳ trường nào trong chiến lược đặt giá thầu mới.campaign_bidding_strategy 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 cần đặt bất kỳ trường phụ nào trong 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 mong muốn.

Ví dụ sau đây tạo 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ó trường con trong mặt nạ cập nhật (để tránh vô tình xoá các trường con) và trả về lỗi FieldMaskError.FIELD_HAS_SUBFIELDS.

Cảnh báo: Mã sau đây 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 cần đặt bất kỳ trường con nào. Tìm hiểu thêm về cách chỉ định chiến lược đặt giá thầu chuẩn và chiến lược đặt giá thầu theo danh mục đầu tư.

Thành công: Mã sau đây cập nhật chiến lược đặt giá thầu của chiến dịch mà không có 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 các trường này vào mặt nạ trường một cách rõ ràng, đồng thời không đặt các trường này 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 giá trị lớn hơn 0.

Đoạn mã sau đây 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 trong 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 cách trường target_cpa_micros trong chiến lược đặt giá thầu MaximizeConversions.

Thành công: Mã sau đây 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 rõ ràng đường dẫn của trường đó vào FieldMask và để trường đó ở trạng thái chưa đặt trên đối tượng tài nguyên.