Cập nhật bằng cách sử dụng mặt nạ tại hiện trường

Trong API Google Ads, quá trình cập nhật được thực hiện bằng cách sử dụng mặt nạ trường. Danh sách mặt nạ trường tất cả các trường mà bạn dự định thay đổi trong bản cập nhật và mọi trường được chỉ định không có trong mặt nạ trường sẽ bị bỏ qua, ngay cả khi được gửi đến máy chủ.

FieldMaskUtil

Bạn nên tạo mặt nạ trường bằng cách sử dụng mặt nạ trường tích hợp sẵn Tiện ích ẩn nhiều thông tin cụ thể và cho phép bạn tạo trường mặt nạ tự động bằng cách giám sát những thay đổi bạn thực hiện đối với các trường của thực thể.

Dưới đây là cách bạn có thể tạo mặt nạ trường để cập nhật chiến dịch:

campaign = client.resource.campaign
campaign.resource_name = client.path.campaign(customer_id, campaign_id)

mask = client.field_mask.with campaign do
  campaign.status = :PAUSED
  campaign.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

Trước tiên, mã sẽ tạo một đối tượng Chiến dịch trống, sau đó đặt tên tài nguyên của mã thành thông báo cho API về chiến dịch đang được cập nhật.

Ví dụ này sử dụng phương thức client.field_mask.with trên chiến dịch để bắt đầu khối bao gồm các nội dung cập nhật. Ở cuối khối này, phần mềm tiện ích so sánh trạng thái hiện tại của chiến dịch sau khi chặn với trạng thái ban đầu trạng thái của chiến dịch trước khi chặn, và tự động tạo một trường mặt nạ liệt kê các trường đã thay đổi. Bạn có thể cung cấp mặt nạ trường đó cho thao tác khi tạo mặt nạ cho lệnh gọi thay đổi như sau:

operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask

Phương pháp này được khuyên dùng khi bạn đang thực hiện một thao tác phức tạp và muốn kiểm soát tốt từng bước. Tuy nhiên, đối với hầu hết các trường hợp, bạn có thể sử dụng Tiện ích thư viện Ruby đơn giản hơn:

operation = client.operation.update_resource.campaign do |c|
  c.status = :PAUSED
  c.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

Phương thức này tự động tạo một tài nguyên chiến dịch trống mới, cấu trúc mặt nạ trường dựa trên những thay đổi bạn thực hiện trong khối, tạo bản cập nhật và trả về thao tác cuối cùng bằng update và update_mask đã được điền sẵn. Bạn cũng có thể chuyển một chiến dịch đến phương thức campaign để đồng thời chỉ định trạng thái bắt đầu của chiến dịch. Mẫu này phù hợp với tất cả các tài nguyên hỗ trợ tác vụ cập nhật.

Tạo mặt nạ theo cách thủ công

Để tạo mặt nạ trường từ đầu mà không cần sử dụng bất kỳ tiện ích thư viện nào, bạn trước tiên sẽ tạo một Google::Protobuf::FieldMask, sau đó tạo một mảng điền tên của tất cả các trường mà bạn dự định thay đổi và cuối cùng gán mảng vào trường path của mặt nạ trường.

mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]

Cập nhật các trường thông báo và trường phụ của các trường đó

Các trường MESSAGE có thể có các trường phụ (chẳng hạn như MaximizeConversions có 3 thuộc tính: target_cpa_micros, cpc_bid_ceiling_micros và cpc_bid_floor_micros) hoặc chúng có thể không có gì (chẳng hạn như ManualCpm).

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

Khi cập nhật trường MESSAGE không được xác định bằng bất kỳ trường phụ nào, hãy sử dụng

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

Khi cập nhật trường MESSAGE được xác định bằng các trường phụ không có cài đặt rõ ràng bất kỳ trường phụ nào trên thông báo đó, bạn phải tự thêm từng trường con MESSAGE có thể thay đổi với FieldMask, tương tự như ví dụ trước đó giúp bạn 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 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 MaximizeConversions chiến lược đặt giá thầu mà không cần thiết lập bất kỳ trường phụ nào trong chiến lược đặt giá thầu.

Trong ví dụ này, việc sử dụng tính năng so sánh tích hợp của FieldMaskUtil sẽ không đạt được mục tiêu đề ra.

Mã sau đây sẽ tạo một mặt nạ trường bao gồm maximize_conversions. Tuy nhiên, API Google Ads không cho phép hành vi này để ngăn chặn vô tình xoá các trường và tạo ra FieldMaskError.FIELD_HAS_SUBFIELDS .

# Creates a campaign with the proper resource name.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# Update the maximize conversions field within the update block, so it's
# captured in the field mask
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions
end

# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
# be included in a field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

Mã sau đây minh hoạ cách cập nhật chiến dịch đúng cách để sử dụng MaximizeConversions chiến lược đặt giá thầu mà không đặt bất kỳ trường phụ nào.

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask is empty. You could modify other
# fields in this block, just not the message field that is intended to have a
# blank subfield. We'll add that below.
campaign_resource_name = client.path.campaign(customer_id, campaign_id)
operation = client.operation.update_resource.campaign(campaign_resource_name) {}

# Manually add the maximize conversions subfield to the field mask so the API
# knows to clear it.
operation.update_mask.paths << "maximize_conversions.target_cpa_micros"

# This operation succeeds.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

Xoá 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. 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à chiến dịch Trường target_cpa_micros được đặt với giá trị lớn hơn 0.

Đoạn mã sau đây chạy; tuy nhiên, maximize_conversions.target_cpa_micros sẽ không được thêm vào mặt nạ trường nên sẽ không có thay đổi nào đối với Trường target_cpa_micros:

# Create a campaign object representing the campaign you want to change.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# The field mask in this operation will include 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it will result in an
# error.
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Operation will fail since field mask is incorrect.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

Mã sau đây minh hoạ cách xoá target_cpa_micros đúng cách trên chiến lược đặt giá thầu MaximizeConversions.

# Create a campaign including the maximize conversions fields right away, since
# we're going to manually add them to the field mask.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Create the operation with an empty field mask. You may add a block here with
# other changes that will automatically get added to the field mask.
operation = client.operation.update_resource.campaign(campaign) {}

# Add the field to the field mask so the API knows to clear it.
operation.update_mask.paths << 'maximize_conversions.target_cpa_micros'

# Operation will succeed since we specified the correct field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

Lưu ý rằng giá trị "không chính xác" mã có hoạt động như dự kiến cho các trường được xác định dưới dạng optional trong API Google Ads protocol buffers. Nhưng vì target_cpa_micros là không phải trường optional, trường "không chính xác" mã không cập nhật tính năng đặt giá thầu để xóa trường target_cpa.