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 naszej wbudowanej maski pola które ukrywa wiele szczegółów i umożliwia generowanie automatycznie nakładają maski, monitorując zmiany wprowadzane w polach encji.
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 na poinformuje API o aktualizacji kampanii.
W tym przykładzie na początku kampanii używana jest metoda client.field_mask.with
obejmujący aktualizacje. Na końcu tego bloku narzędzie
porównuje bieżący stan kampanii po zablokowaniu ze stanem początkowym
stanu kampanii przed zablokowaniem i automatycznie tworzy pole
maską wyliczającą zmienione pola. Tę maskę pola możesz umieścić w funkcji
podczas tworzenia jej dla wywołania mutacji w ten sposób:
operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask
Ta metoda jest zalecana podczas wykonywania skomplikowanej operacji chcą dokładnie kontrolować każdy krok. Jednak w większości przypadków możesz użyć atrybutu prostsze narzędzie biblioteki 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 aktualizację
i zwraca operację końcową z update i update_mask
już wypełnione. Możesz też przekazać kampanię do metody campaign, aby:
określają też stan początkowy kampanii. Ten wzorzec sprawdza się w przypadku wszystkich
zasobów obsługujących operację aktualizacji.
Ręczne tworzenie maski
Aby utworzyć maskę pola od zera, bez użycia narzędzi biblioteki,
utworzyłoby najpierw Google::Protobuf::FieldMask, a następnie tablicę
wypełnione nazwami wszystkich pól, które chcesz zmienić, oraz
przypisać tablicę do pola path maski pola.
mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]
aktualizowanie pól wiadomości i ich pól podrzędnych;
Pola MESSAGE mogą zawierać pola podrzędne (takie jak
MaximizeConversions, która ma 3 elementy:
target_cpa_micros, cpc_bid_ceiling_micros i cpc_bid_floor_micros) lub
nie mogą nie mieć żadnej (np. ManualCpm).
Pola wiadomości bez zdefiniowanych pól podrzędnych
Aktualizując pole MESSAGE, które nie jest zdefiniowane w żadnym polu podrzędnym, użyj funkcji
FieldMaskUtil w celu wygenerowania maski pola, jak zaprezentowaliśmy wcześniej.
Pola wiadomości ze zdefiniowanymi polami podrzędnymi
Podczas aktualizowania pola MESSAGE zdefiniowanego za pomocą podpól bez jawnego ustawiania podpól w danej wiadomości musisz ręcznie dodać wszystkie zmienialne podpola MESSAGE do pola FieldMask, podobnie jak w przykładzie z wcześniejszego tworzenia maski pola od podstaw.
Typowym przykładem jest aktualizacja strategii ustalania stawek w kampanii bez ustawiania żadnych pól w nowej strategii ustalania stawek. Przykład poniżej
pokazuje, jak zaktualizować kampanię, aby korzystała z
Strategia ustalania stawek: MaximizeConversions
bez konfigurowania żadnych pól podrzędnych strategii ustalania stawek.
W tym przykładzie użycie wbudowanego porównania FieldMaskUtil nie w osiągnięciu zamierzonego celu.
Podany kod generuje maskę pola, która zawiera maximize_conversions.
Interfejs Google Ads API nie zezwala jednak na takie zachowanie, aby zapobiec
przypadkowo czyszcząc pola i generuje
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 korzystała z
MaximizeConversions strategia ustalania stawek bez ustawienia żadnego z 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ć bezpośrednio. Podobnie jak w poprzednim przykładzie, musisz wyraźnie dodać te pola do maski pola. Załóżmy na przykład, że masz
kampania wykorzystująca MaximizeConversions strategię ustalania stawek.
W polu target_cpa_micros ustawiono wartość większą niż 0.
Uruchomi się następujący kod: jednak maximize_conversions.target_cpa_micros
nie zostaną dodane do maski pola, więc żadne zmiany nie zostaną wprowadzone w
Pole target_cpa_micros:
# 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
Ten kod pokazuje, jak prawidłowo wyczyścić: 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 "nieprawidłowe" w polach, w których jest zdefiniowany kod, kod działa zgodnie z oczekiwaniami
jako optional w interfejsie Google Ads API protocol buffers. Ponieważ jednak
target_cpa_micros to
inne niż pole optional, „nieprawidłowe” kod nie aktualizuje stawek
aby wyczyścić pole target_cpa.