Maski w terenie

W interfejsie Google Ads API zmiany są wykonywane za pomocą maski pola. Maska pola zawiera wszystkie pola, które chcesz zmienić po aktualizacji, a wszystkie określone pola, które nie są w masce pól, są ignorowane, nawet jeśli zostaną wysłane na serwer. Maskę pola możesz utworzyć ręcznie, tworząc Google\Protobuf\FieldMask. W tym celu tablica zawiera nazwy wszystkich pól, które chcesz zmienić, a następnie przypisujesz ją do pola ścieżki maski pola.

Możesz też skorzystać z wbudowanego narzędzia maski pól (Maski pól), które pozwala ukryć wiele szczegółów i automatycznie generować maski pól przez monitorowanie zmian wprowadzonych w polach elementu.

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));

Najpierw kod ten tworzy obiekt kampanii, a potem ustawia nazwę jej 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 FieldMasks::allSetFieldsOf() do utworzenia maski pola dla kampanii na podstawie wszystkich zmienionych pól. Na koniec przekazuje zwróconą maskę do obiektu operacji kampanii.

FieldMasks::allSetFieldsOf to wygodny sposób na stosowanie FieldMasks::compare(). Porównuje przekazywany obiekt z pustym obiektem tej samej klasy. Na przykład w wcześniejszym kodzie można było użyć kodu 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 z 3 polami: target_cpa_micros, cpc_bid_ceiling_micros i cpc_bid_floor_micros) albo nie mogą zawierać żadnych pól (np. ManualCpm).

Pola wiadomości bez zdefiniowanych pól

Podczas aktualizowania pola MESSAGE, które nie jest zdefiniowane w żadnym polu, użyj FieldMasks do wygenerowania maski pola zgodnie z opisem opisanymi powyżej.

Pola wiadomości ze zdefiniowanymi polami

Podczas aktualizowania pola MESSAGE zdefiniowanego za pomocą pól podrzędnych bez wyraźnego ustawienia dowolnego pola w tej wiadomości, musisz ręcznie dodać każde pole zmienne MESSAGE do maski FieldMask wygenerowanej od zdrapki z tej konkretnej maski.

Typowym przykładem jest aktualizowanie strategii ustalania stawek w kampanii bez ustawiania pól w nowej strategii. Ten kod pokazuje, jak zaktualizować kampanię, by wykorzystywała strategię ustalania stawek MaximizeConversions bez ustawiania pól w strategii ustalania stawek.

W tym przypadku użycie właściwości allSetFieldsOf() i compare() elementu FieldMasks nie prowadzi do celu.

Ten kod generuje maskę pola, która zawiera maximize_conversions. Interfejs Google Ads API nie zezwala jednak na takie działanie, aby uniknąć przypadkowego czyszczenia pól i generowania błędu 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ę, tak aby wykorzystywała strategię ustalania stawek MaximizeConversions bez ustawiania jej pól.

// 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 wyraźnie wyczyścić. Podobnie jak w przykładzie wcześniej, musisz dodać te pola do maski pola. Załóżmy, że masz kampanię, która korzysta ze strategii ustalania stawek MaximizeConversions, a pole target_cpa_micros jest ustawione na wartość większą niż 0.

Uruchamiany jest ten kod, ale maximize_conversions.target_cpa_micros nie zostanie 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]);

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);

Kod &"invalid i quot; działa zgodnie z oczekiwaniami w przypadku pól zdefiniowanych jako optional w interfejsie Google Ads API protocol buffers. Ponieważ jednak target_cpa_micros nie jest polem optional, kod "invalid" nie aktualizuje strategii ustalania stawek tak, aby wyczyścić pole target_cpa.