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

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 객체를 만듭니다. 그런 다음 빈 Campaign 객체를 가져오도록 설정합니다. 그런 다음 해당 캠페인 객체를 업데이트하고 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에 알려줍니다.