Échec partiel

Dans l'API Google Ads, vous pouvez demander que les opérations valides soient validées et que celles qui ont échoué renvoient des erreurs. Cette fonctionnalité, appelée "échec partiel", vous permet de gérer séparément les opérations ayant échoué à la fin. Il est disponible dans les méthodes autres que "get" de nombreux services de l'API Google Ads.

Détails techniques

Pour utiliser cette fonctionnalité, définissez le paramètre partialFailure de la méthode que vous souhaitez utiliser. Cela peut varier légèrement dans chaque bibliothèque cliente. Par exemple, procédez comme suit pour activer cette fonctionnalité lorsque vous envoyez une requête à l'aide de MutateAdGroups :

Java

mutateAdGroups(String.valueOf(customerId), operations, true)

C#

MutateAdGroups(customerId.ToString(), operations, true, false)

PHP

mutateAdGroups($customerId, $operations, ['partialFailure' => true])

Python

mutate_ad_groups(customer_id, operations, partial_failure=True)

Ruby

mutate_ad_groups(customer_id, operations, partial_failure: true)

Perl

mutate({customerId => $customer_id, operations => $operations, partialFailure => 'true'})

Le service effectuera les opérations qui n'ont pas généré d'erreur. Il renvoie les résultats des opérations réussies et les erreurs de celles qui ont échoué.

Utilisation

Supposons que vous deviez ajouter un ensemble de groupes d'annonces à votre compte, mais que certains d'entre eux présentent des problèmes. Vous souhaitez créer les groupes d'annonces valides, mais renvoyer les groupes d'annonces ayant échoué avec leurs erreurs.

Quand éviter l'échec partiel

Vous ne devez pas utiliser l'échec partiel pour les requêtes comportant des opérations interdépendantes.

Par exemple, si vous créez une entité complexe qui nécessite la création de plusieurs ressources dans une même requête, comme une campagne Performance Max, vous ne devez pas utiliser l'échec partiel. La création initiale d'une campagne Performance Max nécessite de créer des ressources Campaign et CampaignAsset dans la même requête. Si la création de Campaign échoue, celle de CampaignAsset échouera également. Vous devez alors considérer la requête comme un échec atomique unique.

Par exemple, n'utilisez pas l'échec partiel lorsque vous ajoutez pour la première fois des composants requis à un AssetGroup. Vous pouvez créer des groupes de composants sans aucun composant ou avec tous les composants requis. Lorsque vous ajoutez des composants à un groupe de composants pour la première fois, vous ne pouvez pas les ajouter un par un dans des demandes distinctes. Vous devez les inclure dans une seule requête et ne pas utiliser d'échec partiel. Une fois que le groupe de composants contient tous les composants requis, vous pouvez en ajouter ou en supprimer un à la fois. Ces requêtes peuvent utiliser l'échec partiel.

Pour déterminer si un échec partiel est approprié, vérifiez si un ID temporaire est nécessaire pour le référencement des ressources inter-opérations dans la même requête. Si tel est le cas, vous ne devez pas utiliser l'échec partiel, car le succès de la deuxième opération dépend de celui de la première.

Créer les opérations et effectuer l'appel d'API

Créez les opérations de mutation et effectuez l'appel d'API comme d'habitude.

Java

private MutateAdGroupsResponse createAdGroups(
    GoogleAdsClient googleAdsClient, long customerId, long campaignId) {
  // This AdGroup should be created successfully - assuming the campaign in the params exists.
  AdGroup group1 =
      AdGroup.newBuilder()
          .setCampaign(ResourceNames.campaign(customerId, campaignId))
          .setName("Valid AdGroup: " + getPrintableDateTime())
          .build();
  // This AdGroup will always fail - campaign ID 0 in resource names is never valid.
  AdGroup group2 =
      AdGroup.newBuilder()
          .setCampaign(ResourceNames.campaign(customerId, 0L))
          .setName("Broken AdGroup: " + getPrintableDateTime())
          .build();
  // This AdGroup will always fail - duplicate ad group names are not allowed.
  AdGroup group3 =
      AdGroup.newBuilder()
          .setCampaign(ResourceNames.campaign(customerId, campaignId))
          .setName(group1.getName())
          .build();

  AdGroupOperation op1 = AdGroupOperation.newBuilder().setCreate(group1).build();
  AdGroupOperation op2 = AdGroupOperation.newBuilder().setCreate(group2).build();
  AdGroupOperation op3 = AdGroupOperation.newBuilder().setCreate(group3).build();

  try (AdGroupServiceClient service =
      googleAdsClient.getLatestVersion().createAdGroupServiceClient()) {
    // Issues the mutate request, setting partialFailure=true.
    return service.mutateAdGroups(
        MutateAdGroupsRequest.newBuilder()
            .setCustomerId(String.valueOf(customerId))
            .setCustomerId(Long.toString(customerId))
            .addAllOperations(Arrays.asList(op1, op2, op3))
            .setPartialFailure(true)
            .build());
  }
}
HandlePartialFailure.java

C#

private static MutateAdGroupsResponse CreateAdGroups(GoogleAdsClient client,
    long customerId, long campaignId)
{
    // Get the AdGroupServiceClient.
    AdGroupServiceClient adGroupService = client.GetService(Services.V22.AdGroupService);

    string validAdGroupName = "Valid AdGroup: " + ExampleUtilities.GetRandomString();

    AdGroupOperation[] operations = new AdGroupOperation[]
    {
        // This operation will be successful, assuming the campaign specified in
        // campaignId parameter is correct.
        new AdGroupOperation()
        {
            Create = new AdGroup()
            {
                Campaign = ResourceNames.Campaign(customerId, campaignId),
                Name = validAdGroupName
            }
        },
        // This operation will fail since we are using campaign ID = 0, which results
        // in an invalid resource name.
        new AdGroupOperation()
        {
            Create = new AdGroup()
            {
                Campaign = ResourceNames.Campaign(customerId, 0),
                Name = "Broken AdGroup: " + ExampleUtilities.GetRandomString()
            },
        },
        // This operation will fail since the ad group is using the same name as the ad
        // group from the first operation. Duplicate ad group names are not allowed.
        new AdGroupOperation()
        {
            Create = new AdGroup()
            {
                Campaign = ResourceNames.Campaign(customerId, campaignId),
                Name = validAdGroupName
            }
        }
    };

    // Add the ad groups.
    MutateAdGroupsResponse response =
        adGroupService.MutateAdGroups(new MutateAdGroupsRequest()
        {
            CustomerId = customerId.ToString(),
            Operations = { operations },
            PartialFailure = true,
            ValidateOnly = false
        });
    return response;
}
HandlePartialFailure.cs

PHP

private static function createAdGroups(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $campaignId
) {
    $campaignResourceName = ResourceNames::forCampaign($customerId, $campaignId);

    // This ad group should be created successfully - assuming the campaign in the params
    // exists.
    $adGroup1 = new AdGroup([
        'name' => 'Valid AdGroup #' . Helper::getPrintableDatetime(),
        'campaign' => $campaignResourceName
    ]);

    // This ad group will always fail - campaign ID 0 in the resource name is never valid.
    $adGroup2 = new AdGroup([
        'name' => 'Broken AdGroup #' . Helper::getPrintableDatetime(),
        'campaign' => ResourceNames::forCampaign($customerId, 0)
    ]);

    // This ad group will always fail - duplicate ad group names are not allowed.
    $adGroup3 = new AdGroup([
        'name' => $adGroup1->getName(),
        'campaign' => $campaignResourceName
    ]);

    $operations = [];

    $adGroupOperation1 = new AdGroupOperation();
    $adGroupOperation1->setCreate($adGroup1);
    $operations[] = $adGroupOperation1;

    $adGroupOperation2 = new AdGroupOperation();
    $adGroupOperation2->setCreate($adGroup2);
    $operations[] = $adGroupOperation2;

    $adGroupOperation3 = new AdGroupOperation();
    $adGroupOperation3->setCreate($adGroup3);
    $operations[] = $adGroupOperation3;

    // Issues the mutate request, enabling partial failure mode.
    $adGroupServiceClient = $googleAdsClient->getAdGroupServiceClient();
    return $adGroupServiceClient->mutateAdGroups(
        MutateAdGroupsRequest::build($customerId, $operations)->setPartialFailure(true)
    );
}
HandlePartialFailure.php