В Google Ads API обновления выполняются с использованием маски поля. В маске поля перечислены все поля, которые вы собираетесь изменить при обновлении, а любые указанные поля, которых нет в маске поля, игнорируются, даже если они отправлены на сервер. Вы можете создать маску поля вручную, создав Google\Protobuf\FieldMask , создав массив, заполненный именами всех полей, которые вы собираетесь изменить, а затем назначив его полю пути маски поля.
Вы также можете использовать нашу встроенную утилиту маски полей ( FieldMasks ), которая скрывает множество конкретных деталей и позволяет автоматически создавать маски полей, отслеживая изменения, вносимые вами в поля сущности.
Вот пример обновления кампании:
$campaign = new Campaign([
'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
'status' => CampaignStatus::PAUSED
]);
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));
Этот код сначала создает объект Campaign, а затем задает имя его ресурса с помощью ResourceNames , чтобы API знал, какая кампания обновляется. status также установлен на PAUSED .
Затем код создает объект CampaignOperation и присваивает ему ранее созданную кампанию. После этого он использует FieldMasks::allSetFieldsOf() для создания маски поля для кампании, используя все измененные поля. Наконец, он передает возвращенную маску объекту операции кампании.
Обратите внимание, что FieldMasks::allSetFieldsOf — удобный метод для FieldMasks::compare() . Он сравнивает переданный объект с пустым объектом того же класса. Например, в более раннем коде вы могли использовать FieldMasks::compare(new Campaign(), $campaign) вместо allSetFieldsOf() .
Обновление полей сообщений и их подполей
Поля MESSAGE могут иметь подполя (например, MaximizeConversions , у которого их три: target_cpa_micros , cpc_bid_ceiling_micros и cpc_bid_floor_micros ) или вообще не иметь их (например, ManualCpm ).
Поля сообщений без определенных подполей
При обновлении поля MESSAGE , которое не определено какими-либо подполями, используйте FieldMasks для создания маски поля, как описано ранее.
Поля сообщений с определенными подполями
При обновлении поля MESSAGE , которое определено с подполями, без явного задания каких-либо подполей в этом сообщении, вы должны вручную добавить каждое из изменяемых подполей MESSAGE в FieldMask , аналогично предыдущему примеру, в котором маска поля создавалась с нуля.
Одним из распространенных примеров является обновление стратегии назначения ставок кампании без задания каких-либо полей в новой стратегии назначения ставок. В приведенном ниже коде показано, как обновить кампанию для использования стратегии назначения ставок MaximizeConversions , не настраивая какие-либо подполя в стратегии назначения ставок.
В этом случае использование методов allSetFieldsOf() и compare() FieldMasks не достигает намеченной цели.
Следующий код генерирует маску поля, включающую в себя maximize_conversions . Однако API Google Рекламы не допускает такого поведения во избежание случайной очистки полей и выдает ошибку 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]);
Следующий код демонстрирует, как правильно обновить кампанию для использования стратегии назначения ставок MaximizeConversions , не задавая ни одного из ее подполей.
// 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);
Очистка полей
Некоторые поля можно очистить явно. Как и в предыдущем примере, вы должны явно добавить эти поля в маску поля. Например, предположим, что у вас есть кампания, в которой используется стратегия назначения ставок MaximizeConversions , и в поле target_cpa_micros установлено значение больше 0 .
Выполняется следующий код; однако maximize_conversions.target_cpa_micros не будет добавлен в маску поля, поэтому в поле target_cpa_micros не вносятся никакие изменения:
// 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]);
Следующий код демонстрирует, как правильно очистить поле target_cpa_micros в стратегии назначения ставок 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);
Обратите внимание, что «неправильный» код работает должным образом для полей, которые определены как optional в protocol buffers API Google Рекламы. Но поскольку поле target_cpa_micros не является optional , «неправильный» код не обновляет стратегию назначения ставок и не очищает поле target_cpa .