Maski terenowe

W interfejsie Google Ads API aktualizacje są przeprowadzane za pomocą maski pola. Maska pola zawiera listę wszystkie pola, które chcesz zmienić w ramach aktualizacji, oraz wszystkie określone pola, których nie ma w masce pola, są ignorowane, nawet jeśli zostały wysłane na serwer. Ty można ręcznie utworzyć maskę pola, tworząc Google\Protobuf\FieldMask tworząc tablicę wypełnioną nazwami wszystkich pól, które chcesz zmienić, i przypisanie jej do pola ścieżki maski pola.

Możesz też użyć naszego wbudowanego narzędzia (FieldMasks), ukrywających wiele szczegółów i umożliwiające generowanie pola, automatycznie nakładają maski, monitorując zmiany wprowadzane 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, a potem ustawia nazwę jego zasobu za pomocą funkcji ResourceNames, dzięki czemu interfejs API będzie wiedzieć, która kampania jest Zaktualizowano. status ma także wartość PAUSED.

Następnie kod tworzy obiekt CampaignOperation i ustawia poprzednią utwórz dla niego kampanię. Potem używa funkcji FieldMasks::allSetFieldsOf() aby utworzyć maskę pola w kampanii przy użyciu wszystkich zmienionych pól. Na koniec przekazuje zwróconą maskę do obiektu operacji kampanii.

Pamiętaj, że FieldMasks::allSetFieldsOf to wygodna metoda: FieldMasks::compare() Porównuje przesłany obiekt z pustym obiektem tej samej klasy. Dla: 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 (takie jak MaximizeConversions, która ma 3 elementy: target_cpa_micros, cpc_bid_ceiling_micros i cpc_bid_floor_micros) albo nie mogą mieć żadnego w ogóle (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, użyj FieldMasks, aby wygenerować maskę pola, jak opisano wcześniej.

Pola wiadomości ze zdefiniowanymi polami podrzędnymi

Podczas aktualizowania pola MESSAGE zdefiniowanego za pomocą pól podrzędnych bez przez ustawienie dowolnego z pól podrzędnych tej wiadomości, musisz ręcznie dodaj każde z zmiennych pól podrzędnych MESSAGE do FieldMask, podobnie jak w poprzednim przykładzie, w którym od zera utworzono maskę pola.

Typowy przykład to aktualizacja strategii ustalania stawek w kampanii bez ustawiania w nowej strategii określania stawek. Poniższy kod ilustruje, jak zaktualizować kampanię, tak aby korzystała z Strategia ustalania stawek: MaximizeConversions bez konfigurowania żadnych pól podrzędnych strategii ustalania stawek.

W tym przypadku za pomocą metod allSetFieldsOf() i compare() funkcji 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 zachowanie, aby zapobiec przypadkowo czyszcząc pola i generuje FieldMaskError.FIELD_HAS_SUBFIELDS .

Ostrzeżenie: poniższy kod powoduje błąd.

// 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ła z MaximizeConversions strategia ustalania stawek bez ustawienia żadnego z pól podrzędnych.

Sukces: poniższy kod pomyślnie zaktualizował strategię ustalania stawek w kampanii.

// 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 bezpośrednio dodaj 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:

Ostrzeżenie: ten kod nie powoduje błędu, ale target_cpa_micros ze strategii ustalania stawek MaximizeConversions nie zostaną usunięte.

// 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 pokazuje, jak prawidłowo wyczyścić: target_cpa_micros w strategii ustalania stawek MaximizeConversions.

Sukces: poniższy kod usuwa target_cpa_micros.

// 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ł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 nie jest polem optional, wyrażenie „nieprawidłowe” kod nie aktualizuje strategię ustalania stawek, aby wyczyścić pole target_cpa.

Ważne: jeśli chcesz wyczyścić pole, najbezpieczniejszym sposobem jest bezpośrednio dodaj to pole do maski pola.