W interfejsie Google Ads API aktualizacje są wprowadzane przy użyciu maski pola. Maska pola zawiera wszystkie pola, które chcesz zmienić w ramach aktualizacji. Wszystkie określone pola, których nie ma w masce pola, są ignorowane, nawet jeśli zostaną wysłane na serwer. Możesz ręcznie utworzyć maskę pola, tworząc Google\Protobuf\FieldMask
, dodając tablicę zawierającą nazwy wszystkich pól, które chcesz zmienić, a potem przypisać ją do pola ścieżki maski pola.
Możesz też użyć naszego wbudowanego narzędzia maski pól (FieldMasks), które ukrywa wiele szczegółowych informacji i umożliwia automatyczne generowanie masek pól przez monitorowanie zmian wprowadzanych w polach encji.
Oto przykład aktualizacji kampanii:
$campaign = new Campaign([
'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
'status' => CampaignStatus::PAUSED
]);
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));
Ten kod najpierw tworzy obiekt kampanii, a potem ustawia jego nazwę zasobu za pomocą ResourceNames
, aby interfejs API wiedział, która kampania jest aktualizowana. status
ma też wartość PAUSED
.
Następnie kod tworzy obiekt CampaignOperation
i ustawia w nim wcześniej utworzoną kampanię. Następnie używa metody FieldMasks::allSetFieldsOf()
do utworzenia maski pól na potrzeby kampanii z wykorzystaniem wszystkich zmienionych pól. Na koniec przekazuje zwróconą maskę do obiektu operacji kampanii.
Pamiętaj, że FieldMasks::allSetFieldsOf
to wygodna metoda w przypadku FieldMasks::compare()
.
Porównuje on przekazany obiekt z pustym obiektem tej samej klasy. Na przykład we wcześniejszym kodzie można było użyć elementu FieldMasks::compare(new
Campaign(), $campaign)
zamiast allSetFieldsOf()
.
aktualizowanie pól wiadomości i ich pól podrzędnych;
Pola MESSAGE
mogą zawierać pola podrzędne (np. MaximizeConversions
, które zawierają 3 pola: target_cpa_micros
, cpc_bid_ceiling_micros
i cpc_bid_floor_micros
), albo mogą nie mieć żadnych pól podrzędnych (np. ManualCpm
).
Pola wiadomości bez zdefiniowanych pól podrzędnych
Gdy aktualizujesz pole MESSAGE
, które nie ma zdefiniowanego żadnego pola podrzędnego, użyj FieldMasks
do wygenerowania maski pola, jak opisano wcześniej.
Pola wiadomości ze zdefiniowanymi polami podrzędnymi
Aktualizując pole MESSAGE
, które jest zdefiniowane za pomocą pól podrzędnych bez ustawiania konkretnych pól podrzędnych w wiadomości, musisz ręcznie dodać do FieldMask
wszystkie zmienne pola podrzędne MESSAGE
, podobnie jak w poprzednim przykładzie, w którym utworzono od zera maskę pola.
Typowym przykładem jest aktualizacja strategii ustalania stawek w kampanii bez ustawiania jakichkolwiek pól w nowej strategii. Poniższy kod pokazuje, jak zaktualizować kampanię, aby korzystać ze strategii ustalania stawek MaximizeConversions
bez konieczności ustawiania żadnych pól podrzędnych tej strategii.
W tym przypadku użycie metod allSetFieldsOf()
i compare()
obiektu FieldMasks
nie pozwala osiągnąć zamierzonego celu.
Poniższy kod generuje maskę pola zawierającą maximize_conversions
.
Interfejs Google Ads API nie zezwala jednak na takie działanie, aby zapobiec przypadkowemu czyszczenia pól i generować błąd FieldMaskError.FIELD_HAS_SUBFIELDS
.
// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
$campaign = new Campaign([
'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
'maximize_conversions' => new MaximizeConversions()
]);
// Constructs an operation, using the FieldMasks' allSetFieldsOf utility to
// derive the update mask. The field mask will include 'maximize_conversions`,
// which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));
// 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.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns($customerId, [$campaignOperation]);
Poniższy kod pokazuje, jak prawidłowo zaktualizować kampanię, aby korzystać ze strategii ustalania stawek MaximizeConversions
bez ustawiania jej pól podrzędnych.
// Creates a Campaign object with the proper resource name.
$campaign = new Campaign([
'resource_name' => ResourceNames::forCampaign($customerId, $campaignId)
]);
// Creates a field mask from the existing campaign and adds all of the mutable
// fields (only one in this case) on the MaximizeConversions bidding strategy to
// the field mask. Because this field is included in the field mask but
// excluded from the campaign object, the Google Ads API will set the campaign's
// bidding strategy to a MaximizeConversions object without any of its subfields
// set.
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 here:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
$fieldMask->setPaths(array_merge(
iterator_to_array($fieldMask->getPaths()->getIterator()),
['maximize_conversions.target_cpa_micros']
));
// Creates an operation to update the campaign with the specified fields.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask($fieldMask);
Czyszczenie pól
Niektóre pola można wyczyścić bezpośrednio. Podobnie jak w poprzednim przykładzie, musisz 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
zawiera wartość większą niż 0
.
Uruchomi się następujący kod, 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:
// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set to 0.
$campaign = new Campaign([
'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
'maximize_conversions' => new MaximizeConversions(['target_cpa' => 0]),
'status' => CampaignStatus::PAUSED
]);
// Constructs an operation, using the FieldMasks' allSetFieldsOf utility to
// derive the update mask. However, the field mask will NOT include
// 'maximize_conversions.target_cpa_micros'.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));
// Sends the operation in a mutate request that will succeed but will NOT update
// the 'target_cpa_micros' field because
// 'maximize_conversions.target_cpa_micros' was not included in the field mask.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns($customerId, [$campaignOperation]);
Poniższy kod pokazuje, jak prawidłowo wyczyścić pole target_cpa_micros
w strategii ustalania stawek MaximizeConversions
.
// Creates a Campaign object with the proper resource name.
$campaign = new Campaign([
'resource_name' => ResourceNames::forCampaign($customerId, $campaignId)
]);
// Constructs a field mask from the existing campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which will
// clear this field from the bidding strategy without impacting any other fields
// on the bidding strategy.
$fieldMask = FieldMasks::allSetFieldsOf($campaign);
$fieldMask->setPaths(array_merge(
iterator_to_array($fieldMask->getPaths()->getIterator()),
['maximize_conversions.target_cpa_micros']
));
// Creates an operation to update the campaign with the specified field.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask($fieldMask);
Pamiętaj, że „nieprawidłowy” kod działa zgodnie z oczekiwaniami w polach zdefiniowanych jako optional
w interfejsie Google Ads API protocol buffers
. Ponieważ jednak target_cpa_micros
nie jest polem optional
, „nieprawidłowy” kod nie aktualizuje pola target_cpa
w strategii ustalania stawek.