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

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

필드 마스크 도우미

필드 마스크를 생성할 때 권장되는 방법은 google.api_core 패키지에 포함된 field_mask 도우미 함수를 사용하는 것입니다. protobuf 객체 두 개를 허용하고, 두 객체 간에 다른 모든 필드가 포함된 list 필드가 있는 필드 마스크 객체를 반환합니다.

None가 첫 번째 매개변수로 전달되면 필드 마스크 목록에는 기본값으로 설정되지 않은 두 번째 protobuf 객체의 모든 필드만 포함됩니다.

생성되면 필드 마스크 객체를 서버로 전송될 작업 객체에 복사해야 합니다.

다음은 캠페인을 업데이트하는 예입니다.

from google.api_core import protobuf_helpers
from google.ads.googleads.client import GoogleAdsClient

# Retrieve a GoogleAdsClient instance.
client = GoogleAdsClient.load_from_storage()
# Create a new campaign operation.
campaign_operation = client.get_type('CampaignOperation')
# Retrieve a new campaign object from its update field.
campaign = campaign_operation.update
# Mutate the campaign.
campaign.network_settings.target_search_network.value = False

# Create a field mask using the updated campaign.
# The field_mask helper is only compatible with raw protobuf message
# instances, which we can access using the ._pb attribute.
field_mask = protobuf_helpers.field_mask(None, campaign._pb)

# Copy the field_mask onto the operation's update_mask field.
client.copy_from(campaign_operation.update_mask, field_mask)

먼저 빈 CampaignOperation 객체를 만듭니다. 그런 다음 빈 캠페인 객체를 검색하도록 설정합니다. 그런 다음 캠페인 객체를 업데이트하고 새 필드 마스크를 만들어 None와 비교합니다. 그러면 변경된 network_settings.target_search_network 필드만 포함하는 필드 마스크 목록이 생성됩니다.

다음은 기존 캠페인을 업데이트하는 예입니다. 여기서는 스크립트가 캠페인의 유효한 리소스 이름과 유효한 customer_id인 resource_name 매개변수를 제공했다고 가정합니다.

import proto

from google.api_core import protobuf_helpers
from google.ads.googleads.client import GoogleAdsClient

# Retrieve a GoogleAdsClient instance.
client = GoogleAdsClient.load_from_storage()
# Retrieve an instance of the GoogleAdsService.
googleads_service = client.get_service('GoogleAdsService')

# Search query to retrieve campaign.
query = f"""
    SELECT
      campaign.network_settings.target_search_network,
      campaign.resource_name
    FROM campaign
    WHERE campaign.resource_name = {resource_name}"""

# Submit a query to retrieve a campaign instance.
response = googleads_service.search_stream(customer_id=customer_id, query=query)

# Iterate over results to retrieve the campaign.
for batch in response:
    for row in batch.results:
        initial_campaign = row.campaign

# Create a new campaign operation.
campaign_operation = client.get_type('CampaignOperation')
# Set the copied campaign object to a variable for easy reference.
updated_campaign = campaign_operation.update
# Copy the retrieved campaign into the new campaign.
# Here we use the proto.Message.copy_from method because of its simple
# compatibility with the protobuf message instances, which are wrapped
# by the proto-plus library.
proto.Message.copy_from(updated_campaign, initial_campaign)
# Mutate the new campaign.
updated_campaign.network_settings.target_search_network = False

# Create a field mask using the updated campaign.
field_mask = protobuf_helpers.field_mask(
    initial_campaign._pb, updated_campaign._pb
)

# Copy the field mask onto the operation's update_mask field.
# Note that the client's copy_from  method is designed to work with both native
# messages and messages wrapped by proto-plus, so it works here for the
# update_mask, even though it's an instance of the native message class
# google.protobuf.field_mask_pb2.FieldMask.
client.copy_from(campaign_operation.update_mask, field_mask)

이 전략에서 updated_campaign는 API에서 가져온 initial_campaign와 동일한 필드, 즉 리소스 이름을 모두 공유합니다. 생성된 필드 마스크는 network_settings.target_search_network 필드만 변경해야 한다고 API에 알립니다.