AI-generated Key Takeaways
-
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:
- Truly empty messages: For example,
campaign.manual_cpmhas no defined subfields. - Messages with optional fields: For example,
campaign.manual_cpchas the optional subfieldenhanced_cpc_enabled.
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:
- Get an empty instance of the message type
(
ManualCpm). - Use
client.copy_fromto assign this empty instance to the campaign's field. - Manually add the field name (
manual_cpm) to theupdate_maskon theCampaignOperation. The field mask helper cannot automatically detect that an empty message has been explicitly set.
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. Manually add "manual_cpm" to the update_mask.
from
google.api_core.protobuf_helpers
import
field_mask
campaign_operation
=
client
.
get_type
(
'CampaignOperation'
)
campaign_operation
.
update
=
campaign
campaign_operation
.
update_mask
=
field_mask
(
None
,
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:
- Instantiate an empty
ManualCpcobject and assign it tocampaign.manual_cpc. - Manually add the path to each mutable subfield of
ManualCpcto theupdate_maskon theCampaignOperation. In this case, the relevant subfield isenhanced_cpc_enabled.
client
=
GoogleAdsClient
.
load_from_storage
()
# Assume 'campaign' is an existing Campaign object you are updating.
# 1. Instantiate and assign an empty ManualCpc
campaign
.
manual_cpc
=
client
.
get_type
(
'ManualCpc'
)
# 2. Manually add the subfield path to the update_mask.
from
google.api_core.protobuf_helpers
import
field_mask
campaign_operation
=
client
.
get_type
(
'CampaignOperation'
)
campaign_operation
.
update
=
campaign
campaign_operation
.
update_mask
=
field_mask
(
None
,
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.
