Set empty message objects as fields

  • Setting empty or optional message fields in the Google Ads API is crucial for specifying bidding strategies for Campaigns.

  • Updating primitive fields like strings can be done directly as object attributes.

  • Updating nested fields with primitive types involves setting attributes on the nested object.

  • To set empty message fields, you need to copy a separate empty instance of the corresponding class onto the campaign object.

  • When updating empty message fields, you must manually add them to the request object's update_mask.

In the Google Ads API, some message fields are used to indicate a choice of bidding strategy for a Campaign. These can be:

Note that bidding strategy fields on Campaign belong to a bidding_strategy oneof group. Setting a new bidding strategy such as manual_cpm or manual_cpc implicitly clears any previously configured bidding strategy in that oneof group.

To update a primitive field like campaign.name, you set it directly:

campaign.name = "Test campaign value"

To update a nested message with settable subfields, like campaign.manual_cpc when enabling enhanced CPC, set it as follows:

campaign.manual_cpc.enhanced_cpc_enabled = True

Set truly empty messages

To use a bidding strategy like manual_cpm, which is an empty message:

  1. Get an empty instance of the message type (ManualCpm).
  2. Use client.copy_from to assign this empty instance to the campaign's field.
  3. Manually add the field name (manual_cpm) to the update_mask on the CampaignOperation. The field mask helper cannot automatically detect that an empty message has been explicitly set.
from google.ads.googleads import util
from google.ads.googleads.client import GoogleAdsClient
from google.api_core.protobuf_helpers import field_mask

client = GoogleAdsClient.load_from_storage()
# Assume 'campaign' is an existing Campaign object you are updating.

# 1. Get an empty ManualCpm type.
empty_cpm = client.get_type("ManualCpm")

# 2. Copy it to the campaign's manual_cpm field.
client.copy_from(campaign.manual_cpm, empty_cpm)

# 3. Create the operation and manually add "manual_cpm" to the update_mask.
campaign_operation = client.get_type("CampaignOperation")
client.copy_from(campaign_operation.update, campaign)
client.copy_from(
    campaign_operation.update_mask,
    field_mask(None, util.convert_proto_plus_to_protobuf(campaign)),
)
campaign_operation.update_mask.paths.append("manual_cpm")

# The resulting proto sent to the API will include:
# manual_cpm {
# }

Set messages with optional subfields

To use manual_cpc as the bidding strategy without enabling enhanced_cpc_enabled, you might try an approach similar to ManualCpm. However, because ManualCpc has subfields, adding manual_cpc to the update_mask results in a FieldMaskError.FIELD_HAS_SUBFIELDS error. The API requires more specificity when a message in the mask has subfields.

To correctly set campaign.manual_cpc while ensuring enhanced_cpc_enabled remains unset:

  1. Instantiate an empty ManualCpc object and copy it into campaign.manual_cpc using client.copy_from.
  2. Manually add the path to each mutable subfield of ManualCpc to the update_mask on the CampaignOperation. In this case, the relevant subfield is enhanced_cpc_enabled.
from google.ads.googleads import util
from google.ads.googleads.client import GoogleAdsClient
from google.api_core.protobuf_helpers import field_mask

client = GoogleAdsClient.load_from_storage()
# Assume 'campaign' is an existing Campaign object you are updating.

# 1. Copy an empty ManualCpc object into campaign.manual_cpc.
client.copy_from(campaign.manual_cpc, client.get_type("ManualCpc"))

# 2. Manually add the subfield path to the update_mask.
campaign_operation = client.get_type("CampaignOperation")
client.copy_from(campaign_operation.update, campaign)
client.copy_from(
    campaign_operation.update_mask,
    field_mask(None, util.convert_proto_plus_to_protobuf(campaign)),
)

# For ManualCpc, because it has subfields, you must specify the subfield
# path in the update_mask. This tells the API you are updating something
# within manual_cpc. By not setting enhanced_cpc_enabled on the campaign
# object, it defaults to false.
campaign_operation.update_mask.paths.append("manual_cpc.enhanced_cpc_enabled")

# The update_mask paths will include: ['manual_cpc.enhanced_cpc_enabled']
# This correctly signals to the API that ManualCpc is the chosen strategy,
# with enhanced_cpc_enabled in its default state.

When sending requests using these patterns, you can verify the payload by enabling logging and inspecting the request.