Masques de champ

Dans l'API Google Ads, les mises à jour sont effectuées à l'aide d'un masque de champ. Le masque de champ répertorie tous les champs que vous souhaitez modifier suite à la mise à jour, ainsi que tous les champs spécifiés ; qui ne sont pas dans le masque de champ sont ignorés, même s'ils sont envoyés au serveur. Toi vous pouvez créer un masque de champ manuellement, Google\Protobuf\FieldMask, créer un tableau rempli avec les noms de tous les champs que vous avez l'intention de modifier, puis je l'attribue au champ de chemin du masque de champ.

Vous pouvez également utiliser notre utilitaire intégré de masque de champ. (FieldMasks) qui masque de nombreux détails spécifiques et vous permet de générer des champs masque automatiquement en surveillant les modifications que vous apportez aux champs de l'entité.

Voici un exemple de mise à jour d'une campagne:

    $campaign = new Campaign([
        'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
        'status' => CampaignStatus::PAUSED
    ]);

    $campaignOperation = new CampaignOperation();
    $campaignOperation->setUpdate($campaign);
    $campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

Ce code crée d'abord un objet Campaign, puis définit le nom de sa ressource à l'aide de la méthode ResourceNames, afin que l'API sache quelle campagne est concernée. mis à jour. status est également défini sur PAUSED.

Le code crée ensuite un objet CampaignOperation et définit l'objet précédemment vous avez créé une campagne. Ensuite, il utilise FieldMasks::allSetFieldsOf() afin de créer un masque de champ pour la campagne en utilisant tous les champs modifiés. Enfin, il transmet le masque renvoyé à l'objet d'opération de campagne.

Notez que FieldMasks::allSetFieldsOf est une méthode pratique pour FieldMasks::compare() Elle compare l'objet transmis à un objet vide de la même classe. Pour dans le code précédent, vous auriez pu utiliser FieldMasks::compare(new Campaign(), $campaign) au lieu de allSetFieldsOf().

Mettre à jour des champs de message et leurs sous-champs

Les champs MESSAGE peuvent comporter des sous-champs (tels que MaximizeConversions, qui en comporte trois: target_cpa_micros, cpc_bid_ceiling_micros et cpc_bid_floor_micros), ou n'en doivent pas (ManualCpm, par exemple).

Champs du message sans sous-champs définis

Lors de la mise à jour d'un champ MESSAGE qui n'est défini avec aucun sous-champ, utilisez FieldMasks pour générer un masque de champ, comme décrit précédemment.

Champs de message avec des sous-champs définis

Lors de la mise à jour d'un champ MESSAGE défini avec des sous-champs sans en définissant explicitement l'un des sous-champs de ce message, vous devez ajoutez chacun des sous-champs MESSAGE modifiables au FieldMask, comme suit : dans l'exemple précédent, qui a créé un masque de champ à partir de zéro.

Par exemple, vous pouvez mettre à jour la stratégie d'enchères d'une campagne sans définir des champs de la nouvelle stratégie d'enchères. Le code ci-dessous montre comment mettre à jour une campagne afin d'utiliser MaximizeConversions stratégie d'enchères sans définir aucun des sous-champs de la stratégie d'enchères.

Dans ce cas, les méthodes allSetFieldsOf() et compare() de la FieldMasks n'atteint pas l'objectif visé.

Le code suivant génère un masque de champ qui inclut maximize_conversions. Toutefois, l'API Google Ads n'autorise pas ce comportement afin d'empêcher si vous effacez accidentellement des champs, 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]);

Le code suivant montre comment mettre à jour correctement une campagne afin d'utiliser la classe MaximizeConversions sans définir aucun de ses sous-champs.

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

Effacer des champs

Certains champs peuvent être explicitement effacés. Comme dans l'exemple précédent, vous devez ajouter explicitement ces champs au masque de champ. Par exemple, supposons que vous avez campagne qui utilise une stratégie d'enchères MaximizeConversions et que la La valeur du champ target_cpa_micros est supérieure à 0.

Le code suivant s'exécute : En revanche, le maximize_conversions.target_cpa_micros ne sont pas ajoutés au masque de champ et aucune modification n'est donc apportée au Champ 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]);

Le code suivant montre comment effacer correctement le target_cpa_micros. de la stratégie d'enchères 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);

Notez que l'erreur "incorrecte" fonctionne comme prévu pour les champs définis en tant que optional dans l'API Google Ads protocol buffers. Mais puisque le target_cpa_micros n'est pas un champ optional, le mot "incorrect" ne met pas à jour le code pour effacer le champ target_cpa.