W interfejsie Google Ads API aktualizacje są przeprowadzane za pomocą maski pola. Maska pola zawiera listę wszystkich pól, które chcesz zmienić w wyniku aktualizacji, a 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
, wykonując tablicę wypełnioną nazwami wszystkich pól, które chcesz zmienić, a następnie przypisując ją do pola ścieżki maski pola.
Możesz też skorzystać z naszego wbudowanego narzędzia maski pól (FieldMasks), które ukrywa wiele szczegółów i umożliwia automatyczne generowanie masek pól przez monitorowanie zmian wprowadzanych w polach encji.
Oto przykład aktualizowania 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 Campaign Managera, a potem ustawia nazwę jego zasobu za pomocą parametru ResourceNames
, aby interfejs API wiedział, która kampania jest aktualizowana. status
ma także wartość PAUSED
.
Następnie kod tworzy obiekt CampaignOperation
i ustawia na niego wcześniej utworzoną kampanię. Następnie za pomocą polecenia FieldMasks::allSetFieldsOf()
tworzy maskę pola dla kampanii, wykorzystując wszystkie zmienione pola. Na koniec przekazuje zwrócona maskę do obiektu operacji kampanii.
FieldMasks::allSetFieldsOf
to wygodna metoda w przypadku FieldMasks::compare()
.
Porównuje przesłany obiekt z pustym obiektem tej samej klasy. Na przykład we wcześniejszym kodzie można było użyć 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 mają 3 elementy: target_cpa_micros
, cpc_bid_ceiling_micros
i cpc_bid_floor_micros
) lub nie mogą zawierać żadnych pól (np. ManualCpm
).
Pola wiadomości bez zdefiniowanych pól podrzędnych
Podczas aktualizowania pola MESSAGE
, które nie jest zdefiniowane w żadnym polu podrzędnym, wygeneruj maskę pola za pomocą FieldMasks
w sposób opisany powyżej.
Pola wiadomości ze zdefiniowanymi polami podrzędnymi
Aktualizując pole MESSAGE
, które jest zdefiniowane za pomocą pól podrzędnych, ale nie ustawiasz żadnych pól podrzędnych tej 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 od zera została utworzona maska pola.
Typowym przykładem jest aktualizowanie strategii ustalania stawek w kampanii bez dodawania nowej strategii ustalania stawek w żadnym z pól. Poniższy kod pokazuje, jak zaktualizować kampanię, aby korzystała ze strategii ustalania stawek MaximizeConversions
bez ustawiania żadnych pól podrzędnych strategii ustalania stawek.
W takim przypadku użycie metod allSetFieldsOf()
i compare()
obiektu FieldMasks
nie osiąga zamierzonego celu.
Ten kod generuje maskę pola zawierającą dyrektywę maximize_conversions
.
Interfejs Google Ads API nie zezwala jednak na takie działanie, aby zapobiec przypadkowemu wyczyszczeniu pól i wywołać 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]);
Ten kod pokazuje, jak prawidłowo zaktualizować kampanię, aby korzystała ze strategii ustalania stawek MaximizeConversions
bez ustawiania żadnych 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 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 pole target_cpa_micros
ma ustawioną wartość większą niż 0
.
Uruchomiony jest poniższy kod. Element maximize_conversions.target_cpa_micros
nie zostanie jednak dodany 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]);
Ten kod ilustruje, 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 prawidłowo 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 strategii ustalania stawek tak, aby wyczyścić pole target_cpa
.