Aggiornamenti che utilizzano maschere di campo

Nell'API Google Ads, gli aggiornamenti vengono eseguiti utilizzando una maschera di campo. La maschera di campo elenca tutti i campi che intendi modificare con l'aggiornamento e tutti i campi specificati che non si trovano nella maschera di campo vengono ignorati, anche se inviati al server.

Assistente per la maschera del campo

Il modo consigliato per generare maschere di campo è utilizzare la funzione helper field_mask inclusa nel pacchetto google.api_core. Accetta due oggetti protobuf e restituisce un oggetto maschera di campo con un elenco paths che contiene tutti i campi diversi tra i due oggetti.

Se None viene passato come primo parametro, l'elenco delle maschere di campo contiene tutti i campi del secondo oggetto protobuf che non sono impostati sul valore predefinito.

Una volta creato, l'oggetto maschera del campo deve essere copiato nell'oggetto operazione che verrà inviato al server.

Aggiornamento da un nuovo oggetto locale

Nell'esempio seguente, crei un oggetto CampaignOperation vuoto e recuperi un oggetto Campaign vuoto dal relativo campo update. Successivamente, modifichi l'oggetto campagna e crei una nuova maschera di campo confrontandola con None, che genera una maschera di campo contenente il campo network_settings.target_search_network modificato:

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

# 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 and set its resource
# name.
campaign = campaign_operation.update
campaign.resource_name = client.get_service("CampaignService").campaign_path(
    customer_id, campaign_id
)

# Mutate the campaign (use direct attribute assignment in proto-plus).
campaign.network_settings.target_search_network = False

# Create a field mask using the updated campaign.
# The field_mask helper is compatible with raw protobuf message instances,
# which you 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)

Aggiornare una risorsa esistente

L'esempio seguente aggiorna una campagna esistente recuperata dall'API, supponendo che resource_name e customer_id siano validi. Con questa strategia, updated_campaign condivide tutti i campi recuperati in initial_campaign (inclusi i relativi resource_name) e la maschera di campo generata indica all'API che è stato modificato solo il campo network_settings.target_search_network:

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

# 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 the campaign. Quote string literals in GAQL.
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.
initial_campaign = None
for batch in response:
    for row in batch.results:
        initial_campaign = row.campaign
        break

if not initial_campaign:
    raise ValueError(f"Campaign '{resource_name}' not found.")

# 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.
# client.copy_from works with both native protobuf messages and messages
# wrapped by the proto-plus library.
client.copy_from(updated_campaign, initial_campaign)

# Mutate the new campaign.
updated_campaign.network_settings.target_search_network = False

# Create a field mask by comparing initial and updated protobuf objects.
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 works with both native messages
# and messages wrapped by proto-plus, including google.protobuf.field_mask_pb2.
client.copy_from(campaign_operation.update_mask, field_mask)

Cancella i campi o imposta messaggi vuoti

Quando il confronto viene eseguito con None, l'helper field_mask ignora i campi impostati su valori vuoti o predefiniti. Per cancellare esplicitamente un campo o impostare un campo messaggio vuoto, aggiungi il percorso del campo direttamente a campaign_operation.update_mask.paths. Per maggiori dettagli, vedi Impostare gli oggetti messaggio vuoti come campi.