필드 마스크를 사용한 업데이트

Google Ads API에서 업데이트는 필드 마스크를 사용하여 이루어집니다. 필드 마스크는 업데이트로 변경하려는 모든 필드와 지정된 필드 필드 마스크에 없는 필드는 서버로 전송되더라도 무시됩니다.

FieldMaskUtil

필드 마스크를 생성할 때 권장되는 방법은 기본 제공 필드 마스크를 사용하는 것입니다. 이 유틸리티는 많은 구체적인 세부정보를 숨기고, 필드를 생성할 수 있게 해 줍니다. 항목의 필드에 대한 변경사항을 모니터링하여 자동으로 마스킹합니다.

캠페인을 업데이트하기 위한 필드 마스크를 생성하는 방법은 다음과 같습니다.

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

이 코드는 먼저 빈 캠페인 객체를 만든 다음 리소스 이름을 API에 업데이트 중인 캠페인을 알립니다.

이 예시에서는 캠페인에서 client.field_mask.with 메서드를 사용하여 업데이트를 포함하는 블록입니다. 이 블록의 끝에서 유틸리티는 차단 후 캠페인의 현재 상태를 차단 전 캠페인의 초기 상태와 비교하고 변경된 필드를 열거하는 필드 마스크를 자동으로 생성합니다. 이 필드 마스크를 연산을 처리해야 합니다.

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

이 메서드는 복잡한 작업을 실행하고 모든 단계를 세부적으로 제어하려는 경우에 권장됩니다. 하지만 대부분의 경우 더 간단한 Ruby 라이브러리 유틸리티입니다.

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

이 방법은 자동으로 새로운 빈 캠페인 리소스를 만들고 블록 내에서 변경한 내용에 따라 필드 마스크를 수정하고 update 및 update_mask가 포함된 최종 작업을 반환합니다. 이미 채워져 있습니다. 캠페인을 campaign 메서드에 전달하여 캠페인의 시작 상태도 지정합니다. 이 패턴은 리소스를 배포합니다

수동으로 마스크 만들기

라이브러리 유틸리티를 사용하지 않고 처음부터 필드 마스크를 만들려면 먼저 Google::Protobuf::FieldMask를 만든 다음 변경하려는 모든 필드의 이름으로 채워진 배열을 만들고 마지막으로 배열을 필드 마스크의 path 필드에 할당합니다.

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

메시지 필드 및 하위 필드 업데이트

MESSAGE 필드에는 하위 필드 (예: 다음 세 가지를 포함하는 MaximizeConversions: target_cpa_micros, cpc_bid_ceiling_micros, cpc_bid_floor_micros) 또는 아무 것도 가질 수 없습니다 (예: ManualCpm).

정의된 하위 필드가 없는 메시지 필드

하위 필드로 정의되지 않은 MESSAGE 필드를 업데이트할 때는 FieldMaskUtil을 사용하여 앞에서 설명한 대로 필드 마스크를 생성합니다.

하위 필드가 정의된 메시지 필드

다음이 없는 하위 필드로 정의된 MESSAGE 필드를 업데이트할 때 명시적으로 해당 메시지의 하위 필드를 명시적으로 설정하려면 FieldMask의 변경 가능한 각 MESSAGE 하위 필드를 처음부터 필드 마스크를 만든 이전 예시입니다.

한 가지 일반적인 예는 새 입찰 전략의 모든 필드 다음 예를 참고하세요. 는 MaximizeConversions 입찰 전략 로 확장됩니다.

이 예에서 내장된 FieldMaskUtil의 비교를 사용해도 달성할 수 있게 될 것입니다

다음 코드는 maximize_conversions를 포함하는 필드 마스크를 생성합니다. 그러나 Google Ads API에서는 트래픽이 실패하는 것을 방지하기 위해 실수로 필드를 지워서 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],
)

다음 코드는 하위 필드를 설정하지 않은 MaximizeConversions 입찰 전략이 있습니다.

성공: 아래 코드로 캠페인 입찰 전략이 업데이트됩니다.

# 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],
)

필드 지우기

일부 필드는 명시적으로 지울 수 있습니다. 이전 예와 마찬가지로 이러한 필드를 필드 마스크에 명시적으로 추가해야 합니다. 예를 들어 MaximizeConversions 입찰 전략을 사용하는 캠페인이 있고 target_cpa_micros 필드가 0보다 큰 값으로 설정되어 있다고 가정해 보겠습니다.

다음 코드는 실행되지만 maximize_conversions.target_cpa_micros가 필드 마스크에 추가되지 않으므로 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

다음 코드는 target_cpa_micros를 올바르게 지우는 방법을 보여줍니다. MaximizeConversions 입찰 전략의 필드입니다.

성공: 다음 코드는 target_cpa_micros을 지웁니다.

# 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

'잘못된' 정의된 필드에서 코드가 제대로 작동하지 Google Ads API protocol buffers에서 optional으로 표현합니다. 그러나 target_cpa_micros: optional 필드가 아닙니다. '잘못됨' 코드가 입찰을 업데이트하지 않음 전략을 사용하여 target_cpa 필드를 지웁니다.

핵심사항: 필드를 지우려는 경우 가장 안전한 방법은 해당 필드를 필드 마스크에 명시적으로 추가하는 것입니다.