W interfejsie Google Ads API aktualizacje są przeprowadzane przy użyciu maski pola. Maska pola zawiera listę wszystkich pól, które chcesz zmienić w ramach aktualizacji. Wszystkie określone pola, które nie znajdują się w masce pola, są ignorowane, nawet jeśli zostaną wysłane na serwer.
FieldMaskUtil
Zalecamy generowanie masek pól za pomocą naszego wbudowanego narzędzia do masek pól, które ukrywa wiele szczegółów i umożliwia automatyczne generowanie masek pól przez monitorowanie zmian wprowadzanych w polach jednostki.
Oto jak wygenerować maskę pola do 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 następnie ustawia jego nazwę zasobu, aby poinformować interfejs API o aktualizowanej kampanii.
W tym przykładzie używamy metody client.field_mask.with w kampanii, aby rozpocząć blok obejmujący aktualizacje. Na końcu tego bloku narzędzie porównuje bieżący stan kampanii po bloku z początkowym stanem kampanii przed blokiem i automatycznie tworzy maskę pola, która zawiera listę zmienionych pól. Możesz podać tę maskę pola w operacji podczas jej tworzenia na potrzeby wywołania mutate w ten sposób:
operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask
Zalecamy tę metodę, 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 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 nowe, puste zasoby kampanii, konstruuje maskę pola na podstawie zmian wprowadzonych w bloku, tworzy operację aktualizacji i zwraca ostateczną operację z już wypełnionymi polami update i update_mask. Możesz też przekazać kampanię do metody campaign, aby określić stan początkowy kampanii. Ten wzorzec działa w przypadku wszystkich zasobów, które obsługują operację aktualizacji.
Ręczne tworzenie maski
Aby utworzyć maskę pola od zera, bez użycia żadnych narzędzi biblioteki, najpierw utwórz Google::Protobuf::FieldMask, a następnie utwórz tablicę wypełnioną nazwami wszystkich pól, które chcesz zmienić, i na koniec przypisz 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ą mieć pola podrzędne (np. MaximizeConversions, które ma 3 pola podrzędne: target_cpa_micros, cpc_bid_ceiling_micros i cpc_bid_floor_micros) lub nie mieć ich wcale (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 FieldMaskUtil, aby wygenerować maskę pola, jak pokazano wcześniej.
Pola wiadomości ze zdefiniowanymi podpola
Podczas aktualizowania pola MESSAGE zdefiniowanego za pomocą pól podrzędnych bez wyraźnego ustawiania żadnego z tych pól w wiadomości musisz ręcznie dodać każde z zmiennych pól podrzędnych MESSAGE do FieldMask, podobnie jak w poprzednim przykładzie, w którym maska pola została utworzona od zera.
Jednym z częstych przykładów jest aktualizacja strategii ustalania stawek w kampanii bez ustawiania żadnych 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 przykładzie użycie wbudowanej funkcji porównywania klasy FieldMaskUtil nie pozwala osiągnąć zamierzonego celu.
Poniższy kod generuje maskę pola, która zawiera maximize_conversions.
Interfejs Google Ads API nie zezwala jednak na takie działanie, aby zapobiec przypadkowemu czyszczeniu pól. W takim przypadku zwraca błąd 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 ze 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ć w sposób jawny. Podobnie jak w poprzednim przykładzie musisz jawnie dodać te pola do maski pola. 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 dodany 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 „nieprawidłowy” kod działa zgodnie z przeznaczeniem w przypadku pól zdefiniowanych jako optional w interfejsie Google Ads API protocol buffers. Ponieważ jednak pole target_cpa_micros nie jest polem optional, „nieprawidłowy” kod nie aktualizuje strategii ustalania stawek, aby wyczyścić pole target_cpa.