Maski w polu

W interfejsie Google Ads API aktualizacje są przeprowadzane za pomocą maski pola. Maska pola (google.protobuf.FieldMask) zawiera listę ścieżek pól w snake_case, które chcesz zmienić za pomocą aktualizacji. Wszystkie określone pola, których nie ma w masce pola, są ignorowane, nawet jeśli zostaną wysłane na serwer.

Narzędzie FieldMasks

Zalecanym sposobem generowania masek pól w bibliotece klienta w Javie 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 aktualizacji kampanii:

// Creates a Campaign object with the proper resource name and any other
// changes.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation that updates the campaign, using the
// FieldMasks.allSetFieldsOf utility to derive the update mask. This mask tells
// the Google Ads API which attributes of the campaign you want to change.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

W tym przykładzie najpierw tworzony jest pusty obiekt Campaign i ustawiana jest jego nazwa zasobu, aby interfejs API wiedział, która kampania jest aktualizowana.

W przykładzie wywoływana jest funkcja FieldMasks.allSetFieldsOf() w kampanii, aby automatycznie utworzyć maskę pola, która zawiera wszystkie ustawione pola. Zwróconą maskę możesz przekazać bezpośrednio do wywołania aktualizacji.

Jeśli chcesz pracować z istniejącym obiektem i zaktualizować kilka pól, użyj FieldMasks.compare() w ten sposób:

// Assumes existingCampaign was retrieved from a previous API call.

// Creates a new campaign based on the existing campaign and updates the
// campaign by setting its status to paused.
Campaign campaignToUpdate =
    existingCampaign.toBuilder()
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation that updates the campaign, using the
// FieldMasks.compare utility to derive the update mask. This mask tells the
// Google Ads API which attributes of the campaign you want to change.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaignToUpdate)
        .setUpdateMask(FieldMasks.compare(existingCampaign, campaignToUpdate))
        .build();

// Sends the operation in a mutate request.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

Aby utworzyć maskę pola od zera, utwórz FieldMask konstruktor i dodaj snake_case nazwę każdego pola, które chcesz zmienić:

FieldMask fieldMask =
    FieldMask.newBuilder()
        .addPaths("status")
        .addPaths("name")
        .build();

Aktualizowanie pól wiadomości i ich pól podrzędnych

Pola MESSAGE mogą mieć pola podrzędne (np. MaximizeConversions, które ma pola target_cpa_micros, cpc_bid_ceiling_micros i cpc_bid_floor_micros) lub nie mieć pól podrzędnych (np. ManualCpm).

Pola wiadomości bez zdefiniowanych podpól

Podczas aktualizowania pola MESSAGE, które nie jest zdefiniowane za pomocą żadnych pól podrzędnych, użyj narzędzia FieldMasks do wygenerowania maski pola, jak opisano w poprzedniej sekcji.

Pola wiadomości ze zdefiniowanymi podpola

Podczas aktualizowania pola MESSAGE, które ma zdefiniowane pola podrzędne bez wyraźnego ustawiania żadnego z nich w danej wiadomości, musisz ręcznie dodać każde z zmiennych pól podrzędnych MESSAGE do FieldMask, podobnie jak w przypadku tworzenia maski pola od zera.

Typowym przykładem jest aktualizacja strategii ustalania stawek w kampanii (pole oneofcampaign_bidding_strategy) bez ustawiania żadnego z pól w nowej strategii ustalania stawek. Poniższy przykład pokazuje, jak zaktualizować kampanię, aby korzystała ze strategii ustalania stawek MaximizeConversions bez ustawiania żadnych pól podrzędnych w tej strategii.

W tym przypadku użycie samych metod allSetFieldsOf() i compare()FieldMasks nie przyniesie zamierzonego efektu.

W tym przykładzie generowana jest maska pola, która zawiera maximize_conversions. Interfejs Google Ads API nie zezwala jednak na ścieżki komunikatów najwyższego poziomu, które mają pola podrzędne w masce aktualizacji (aby zapobiec przypadkowemu wyczyszczeniu pól podrzędnych), i zwraca błąd FieldMaskError.FIELD_HAS_SUBFIELDS.

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setMaximizeConversions(MaximizeConversions.newBuilder().build())
        .build();

// Constructs an operation using FieldMasks.allSetFieldsOf to derive the update
// mask. The field mask includes 'maximize_conversions', which produces a
// FieldMaskError.FIELD_HAS_SUBFIELDS error.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request that results in a
// FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields with
// subfields cannot be included directly in a field mask.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

Poniższy przykład pokazuje, jak prawidłowo zaktualizować kampanię, aby używała strategii ustalania stawek MaximizeConversions bez ustawiania żadnych jej pól podrzędnych. Dowiedz się więcej o przypisywaniu standardowych strategii ustalania stawek i strategii portfolio ustalania stawek.

// Creates a Campaign object with the proper resource name.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .build();

// Creates a field mask from the campaign and adds the mutable subfield
// ('maximize_conversions.target_cpa_micros') on the MaximizeConversions
// bidding strategy to the field mask. Because this subfield is included in the
// field mask while excluded from the campaign object, the Google Ads API
// switches the campaign's bidding strategy oneof to MaximizeConversions with
// target_cpa_micros unset.
FieldMask fieldMask =
    FieldMasks.allSetFieldsOf(campaign).toBuilder()
        .addPaths("maximize_conversions.target_cpa_micros")
        .build();

// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(fieldMask)
        .build();

Wyczyść pola

Niektóre pola można wyraźnie wyczyścić. Podobnie jak w poprzednim przykładzie musisz jawnie dodać te pola do maski pola, pozostawiając je nieustawione w obiekcie wiadomości. Załóżmy na przykład, że masz kampanię, która korzysta ze strategii ustalania stawek MaximizeConversions, a pole target_cpa_micros ma wartość większą niż 0.

Poniższy kod zostanie uruchomiony, ale maximize_conversions.target_cpa_micros nie zostanie wyczyszczony zgodnie z oczekiwaniami:

// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set to 0L.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setMaximizeConversions(
            MaximizeConversions.newBuilder().setTargetCpaMicros(0L).build())
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation using FieldMasks.allSetFieldsOf to derive the
// update mask.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request that does not clear the field
// cleanly.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

W następnym przykładzie pokazujemy, jak prawidłowo wyczyścić pole target_cpa_micros w strategii ustalania stawek MaximizeConversions.

// Creates a Campaign object with the proper resource name.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .build();

// Constructs a field mask from the 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).toBuilder()
        .addPaths("maximize_conversions.target_cpa_micros")
        .build();

// Creates an operation to update the campaign with the specified field.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(fieldMask)
        .build();