Falla parcial

En la API de Google Ads, puedes solicitar que se confirmen las operaciones válidas y que las que fallaron muestren errores. Esta función, llamada falla parcial, te permite controlar las operaciones fallidas por separado al final. Está disponible en los métodos que no son de obtención de muchos servicios de la API de Google Ads.

Detalles técnicos

Para utilizar esta función, establece el parámetro partialFailure del método que deseas usar. Esto puede variar un poco en cada biblioteca cliente. Por ejemplo, haz lo siguiente para activar esta función cuando envíes una solicitud con 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'})

El servicio llevará a cabo las operaciones que no tuvieron errores. Devolverá resultados para las operaciones exitosas y errores para las fallidas.

Uso

Supongamos que necesitas agregar un conjunto de grupos de anuncios a tu cuenta, pero algunos de ellos pueden tener problemas. Deseas crear los grupos de anuncios válidos, pero que se muestren los grupos de anuncios fallidos junto con sus errores.

Cuándo evitar la falla parcial

No debes usar la falla parcial para las solicitudes con operaciones interdependientes.

Por ejemplo, si creas una entidad compleja que requiere que se creen varios recursos en una sola solicitud, como una campaña de máximo rendimiento, no debes usar la falla parcial. La creación inicial de una campaña de máximo rendimiento requiere la creación de recursos Campaign y CampaignAsset en la misma solicitud. Si falla la creación de Campaign, también fallará la creación de CampaignAsset, y debes tratar la solicitud como un solo error atómico.

Como otro ejemplo, no uses la falla parcial cuando agregues por primera vez recursos obligatorios a un objeto AssetGroup. Los grupos de recursos se pueden crear sin recursos o con todos los recursos obligatorios. Cuando agregas recursos a un grupo de recursos por primera vez, no puedes agregarlos uno a la vez en solicitudes separadas. Debes incluirlos todos en una sola solicitud y no debes usar fallas parciales. Después de que el grupo de recursos tenga todos los recursos obligatorios, puedes agregar o quitar recursos de a uno por vez, y esas solicitudes pueden usar fallas parciales.

Para determinar si el error parcial es adecuado, verifica si se necesita un ID temporal para hacer referencia a recursos entre operaciones dentro de la misma solicitud. Si es así, no debes usar la falla parcial, ya que el éxito de la segunda operación depende del éxito de la primera.

Crea las operaciones y realiza la llamada a la API

Crea las operaciones de mutación y realiza la llamada a la API como de costumbre.

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