Maski w polu

W interfejsie Google Ads API maska pola służy do podawania listy pól, które żądanie do interfejsu API powinno zaktualizować. Wszystkie pola, które nie są określone w polu maski, są ignorowane, nawet jeśli zostaną wysłane na serwer.

Klasa FieldMasks

Zalecanym sposobem generowania masek pól w bibliotece klienta .NET jest użycie wbudowanej klasy narzędziowej FieldMasks, która umożliwia generowanie masek pól ze zmodyfikowanego obiektu zamiast tworzenia ich od zera.

Oto przykład aktualizowania kampanii, która używa metody FieldMasks.AllSetFieldsOf do tworzenia maski pola zawierającej wszystkie ustawione pola. Wygenerowaną maskę pola możesz następnie przekazać bezpośrednio do wywołania aktualizacji:

// Update campaign by setting its status to paused, and "Search network" to
// false.
Campaign campaignToUpdate = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
    NetworkSettings = new NetworkSettings()
    {
        TargetSearchNetwork = false
    }
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};

// Update the campaign.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

Czasami musisz pracować z istniejącym obiektem i zaktualizować kilka pól. W takich przypadkach użyj metody FieldMasks.FromChanges. Ta metoda generuje maskę pola, która reprezentuje różnicę między 2 obiektami:

Campaign existingCampaign;

// Obtain existingCampaign from an earlier API call.

// Create a new campaign based on the existing campaign for update.
Campaign campaignToUpdate = new Campaign(existingCampaign);

// Update campaign by setting its status to paused, and "Search network" to
// false.
campaignToUpdate.Status = CampaignStatus.Paused;
campaignToUpdate.NetworkSettings = new NetworkSettings()
{
    TargetSearchNetwork = false
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.FromChanges(existingCampaign, campaignToUpdate)
};

Obsługa błędów FieldMaskError.FIELD_HAS_SUBFIELDS

W rzadkich przypadkach może być konieczne ustawienie pola wiadomości bez aktualizowania żadnego z jego pól podrzędnych. Przyjrzyj się temu przykładowi:

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = new MaximizeConversions()
};

CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

To wywołanie interfejsu API kończy się niepowodzeniem i zwraca błąd FieldMaskError.FIELD_HAS_SUBFIELDS. Ponieważ pole MaximizeConversions ma pola podrzędne, serwer interfejsu Google Ads API oczekuje, że w żądaniu będą obecne maski pól dla modyfikowalnych pól podrzędnych. W tej sytuacji FieldMasks nie może automatycznie generować masek pól podrzędnych, ponieważ w żądaniu nie ustawiono żadnych pól podrzędnych.

W takich przypadkach możesz ręcznie dodać ścieżki do fieldMask.Paths (który jest RepeatedField<string>):

// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
};

FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
// Only include 'maximize_conversions.target_cpa_micros' in the field mask
// as it is the only mutable subfield on MaximizeConversions when used as a
// standard bidding strategy.
//
// Learn more about standard and portfolio bidding strategies at:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
fieldMask.Paths.Add("maximize_conversions.target_cpa_micros");

// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = fieldMask
};

Wyczyść pola

Interfejs Google Ads API obsługuje czyszczenie niektórych wartości pól. Aby wyczyścić pole, musisz ręcznie uwzględnić je w masce pola, pozostawiając je nieustawione w obiekcie zasobu. Ustawienie pola na wartość domyślną (np. 0 w przypadku pola int64) nie powoduje wyczyszczenia pola.

Poniższy przykładowy kod pokazuje, jak wyczyścić pole target_cpa_micros strategii ustalania stawek MaximizeConversions:

Prawidłowy kod

Poniższy kod czyści pole target_cpa_micros, ponieważ dodaje maximize_conversions.target_cpa_micros do maski pola bez ustawiania właściwości campaign.MaximizeConversions.TargetCpaMicros:

// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
};

// Constructs a field mask from the existing campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which
// clears this field from the bidding strategy without impacting any other
// fields on the bidding strategy.
FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
fieldMask.Paths.Add("maximize_conversions.target_cpa_micros");

// Creates an operation to update the campaign with the specified field.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = fieldMask
};

Nieprawidłowy kod

Poniższy kod nie czyści pola target_cpa_micros, ponieważ ustawia w nim wartość 0. Zarówno narzędzie FieldMasks, jak i serwer interfejsu Google Ads API ignorują tę wartość, gdy TargetCpaMicros ma wartość 0 lub gdy ścieżka jest pominięta w masce, a serwer nie zwraca błędu:

// Creates a campaign with the proper resource name and a
// MaximizeConversions object. Attempts to clear the target_cpa_micros
// field by setting it to 0.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = new MaximizeConversions()
    {
        TargetCpaMicros = 0
    }
};

// Constructs an operation using FieldMasks.AllSetFieldsOf to derive the
// update mask.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

// Sends the operation in a mutate request that succeeds without clearing
// the previous 'target_cpa_micros' value cleanly.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });