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ć. Każde pole, które nie jest określone w masce pola, jest ignorowane, nawet jeśli zostało wysłane na serwer.

Klasa FieldMasks

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

Oto przykład aktualizowania kampanii, która używa metody FieldMasks.AllSetFieldsOf do utworzenia maski pola zawierającej wszystkie ustawione pola. Następnie możesz przekazać wygenerowaną maskę pola 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 może być konieczne użycie istniejącego obiektu i zaktualizowanie kilku 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 nie powiedzie się i zostanie zwrócony błąd FieldMaskError.FIELD_HAS_SUBFIELDS. Ponieważ MaximizeConversions ma pola podrzędne, serwer interfejsu Google Ads API oczekuje, że w żądaniu będą obecne maski pól podrzędnych, które można modyfikować. Jednak w tej sytuacji FieldMasks nie może automatycznie wygenerować masek podpól, ponieważ żądanie nie ustawia żadnych podpól.

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 wartości domyślnej pola (np. 0 w przypadku pola int64) nie powoduje jego wyczyszczenia.

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

Prawidłowy kod

Ten 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 je na 0. Zarówno narzędzie FieldMasks, jak i serwer interfejsu Google Ads API ignorują tę wartość, gdy TargetCpaMicros to 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 });