W interfejsie Google Ads API aktualizacje są przeprowadzane za pomocą maski pola. Maska pola zawiera listę wszystkich pól, które chcesz zmienić w ramach aktualizacji. Wszystkie pola, które nie znajdują się w masce, są ignorowane, nawet jeśli zostaną wysłane na serwer.
FieldMaskUtil
Zalecanym sposobem generowania masek pól jest użycie wbudowanego narzędzia do generowania masek pól, które ukrywa wiele szczegółowych informacji i umożliwia automatyczne generowanie masek pól na podstawie zmian wprowadzonych w polach danego elementu.
Aby wygenerować maskę pola na potrzeby aktualizacji kampanii:
campaign = client.resource.campaign
campaign.resource_name = client.path.campaign(customer_id, campaign_id)
mask = client.field_mask.with campaign do
campaign.status = :PAUSED
campaign.network_settings = client.resource.network_settings do |ns|
ns.target_search_network = false
end
end
Kod najpierw tworzy pusty obiekt Campaign, a potem ustawia jego nazwę zasobu, aby poinformować interfejs API o zmienianej kampanii.
W tym przykładzie do rozpoczęcia bloku obejmującego aktualizacje używamy metody client.field_mask.with w kampanii. Na końcu tego bloku narzędzie porównuje bieżący stan kampanii po wprowadzeniu blokady ze stanem kampanii przed wprowadzeniem blokady i automatycznie generuje maskę pól, która wylicza zmienione pola. Możesz podać tę maskę pola podczas tworzenia operacji dla wywołania metody mutate w ten sposób:
operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask
Ta metoda jest zalecana, gdy wykonujesz skomplikowaną operację i chcesz mieć pełną kontrolę nad każdym krokiem. W większości przypadków możesz jednak użyć prostszego narzędzia Ruby:
operation = client.operation.update_resource.campaign do |c|
c.status = :PAUSED
c.network_settings = client.resource.network_settings do |ns|
ns.target_search_network = false
end
end
Ta metoda automatycznie tworzy nowy pusty zasób kampanii, tworzy maskę pola na podstawie zmian wprowadzonych w bloku, tworzy operację aktualizacji i zwraca operację końcową z wstępnie wypełnionymi polami update i update_mask. Możesz też przekazać kampanię metodzie campaign, aby określić stan początkowy kampanii. Ten wzór działa w przypadku wszystkich zasobów, które obsługują operację aktualizacji.
Ręczne tworzenie maski
Aby utworzyć maskę pola od podstaw, bez używania żadnych narzędzi biblioteki, musisz najpierw utworzyć Google::Protobuf::FieldMask, a następnie tablicę wypełnioną nazwami wszystkich pól, które chcesz zmienić, i w końcu przypisać tablicę do pola path maski pola.
mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]
Aktualizowanie pól wiadomości i ich podpól
Pola MESSAGE mogą mieć pola podrzędne (np. MaximizeConversions, które ma 3 pola: target_cpa_micros, cpc_bid_ceiling_micros i cpc_bid_floor_micros), albo w ogóle ich nie mieć (np. ManualCpm).
Pola wiadomości bez zdefiniowanych pól podrzędnych
Podczas aktualizowania pola MESSAGE, które nie jest zdefiniowane za pomocą żadnych pól podrzędnych, użyj FieldMaskUtil, aby wygenerować maskę pola, jak opisano wcześniej.
Pola wiadomości z zdefiniowanymi podpolami
Podczas aktualizowania pola MESSAGE zdefiniowanego za pomocą podpól bez jawnego ustawiania podpól w danej wiadomości musisz ręcznie dodać do pola FieldMask wszystkie zmienialne podpola MESSAGE, podobnie jak w przykładzie z wcześniejszej części, w którym maska pola została utworzona od podstaw.
Typowym przykładem jest aktualizacja strategii ustalania stawek w kampanii bez ustawiania żadnych pól w nowej strategii ustalania stawek. W tym przykładzie pokazujemy, jak zaktualizować kampanię, aby używała strategii ustalania stawek MaximizeConversions bez ustawiania żadnych podpól strategii ustalania stawek.
W tym przykładzie użycie wbudowanego porównania FieldMaskUtil nie osiąga zamierzonego celu.
Podany niżej kod generuje maskę pola, która zawiera maximize_conversions.
Interfejs Google Ads API nie zezwala jednak na takie działanie, aby zapobiec przypadkowemu oczyszczeniu pól i wystąpieniu błędu FieldMaskError.FIELD_HAS_SUBFIELDS.
# Creates a campaign with the proper resource name.
campaign = client.resource.campaign do |c|
c.resource_name = client.path.campaign(customer_id, campaign_id)
end
# Update the maximize conversions field within the update block, so it's
# captured in the field mask
operation = client.operation.update_resource.campaign(campaign) do |c|
c.maximize_conversions = client.resource.maximize_conversions
end
# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
# be included in a field mask.
response = client.service.campaign.mutate_campaigns(
customer_id: customer_id,
operations: [operation],
)
Poniższy kod pokazuje, jak prawidłowo zaktualizować kampanię, aby używała strategii ustalania stawek MaximizeConversions bez ustawiania żadnych jej pól podrzędnych.
# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask is empty. You could modify other
# fields in this block, just not the message field that is intended to have a
# blank subfield. We'll add that below.
campaign_resource_name = client.path.campaign(customer_id, campaign_id)
operation = client.operation.update_resource.campaign(campaign_resource_name) {}
# Manually add the maximize conversions subfield to the field mask so the API
# knows to clear it.
operation.update_mask.paths << "maximize_conversions.target_cpa_micros"
# This operation succeeds.
response = client.service.campaign.mutate_campaigns(
customer_id: customer_id,
operations: [operation],
)
Czyszczenie pól
Niektóre pola można wyczyścić. Podobnie jak w poprzednim przykładzie, musisz wyraźnie dodać te pola do maski pola. Załóżmy na przykład, że masz kampanię, która korzysta ze strategii ustalania stawek MaximizeConversions, a w polu target_cpa_micros ustawiona jest wartość większa niż 0.
Ten kod jest wykonywany, ale pole maximize_conversions.target_cpa_micros nie zostanie dodane do maski pola, więc w polu target_cpa_micros nie zostaną wprowadzone żadne zmiany:
# Create a campaign object representing the campaign you want to change.
campaign = client.resource.campaign do |c|
c.resource_name = client.path.campaign(customer_id, campaign_id)
end
# The field mask in this operation will include 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it will result in an
# error.
operation = client.operation.update_resource.campaign(campaign) do |c|
c.maximize_conversions = client.resource.maximize_conversions do |mc|
mc.target_cpa_micros = 0
end
end
# Operation will fail since field mask is incorrect.
response = client.service.campaign.mutate_campaigns(
customer_id: customer_id,
operations: [operation],
end
Poniższy kod pokazuje, jak prawidłowo wyczyścić pole target_cpa_micros w strategii ustalania stawek MaximizeConversions.
# Create a campaign including the maximize conversions fields right away, since
# we're going to manually add them to the field mask.
campaign = client.resource.campaign do |c|
c.resource_name = client.path.campaign(customer_id, campaign_id)
c.maximize_conversions = client.resource.maximize_conversions do |mc|
mc.target_cpa_micros = 0
end
end
# Create the operation with an empty field mask. You may add a block here with
# other changes that will automatically get added to the field mask.
operation = client.operation.update_resource.campaign(campaign) {}
# Add the field to the field mask so the API knows to clear it.
operation.update_mask.paths << 'maximize_conversions.target_cpa_micros'
# Operation will succeed since we specified the correct field mask.
response = client.service.campaign.mutate_campaigns(
customer_id: customer_id,
operations: [operation],
end
Pamiętaj, że kod „incorrect” działa zgodnie z oczekiwaniami w przypadku pól zdefiniowanych jako optional w interfejsie Google Ads API protocol buffers. Ponieważ jednak pole target_cpa_micros nie jest polem optional, kod „incorrect” nie aktualizuje strategii ustalania stawek, aby wyczyścić pole target_cpa.