部分失败

Google Ads API 中的部分失败功能允许提交请求中的成功操作，同时仅针对失败的操作返回错误。此功能称为部分失败，允许您在结束时单独处理失败的操作。很多 Google Ads API 服务的非 GET 方法都支持该功能。

技术详情

如需使用此功能，请设置您要使用的方法的 partialFailure 参数。这在每个客户端库中都可能略有不同。例如，执行以下代码，即可在使用 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'})

该服务将执行没有错误的操作。它将返回成功操作的结果和失败操作的错误。

用法

假设您需要向账号添加一组广告组，但部分广告组可能存在一些问题。您希望创建有效的广告组，但返回失败的广告组及其错误。

何时避免部分失败

对于包含相互依赖的操作的请求，您不应使用部分失败。

例如，如果您要创建复杂的实体（例如效果最大化广告系列），需要在单个请求中创建多个资源，则不应使用部分失败。首次制作效果最大化广告系列时，需要在同一请求中制作 Campaign 和 CampaignAsset 资源。如果 Campaign 创建失败，CampaignAsset 创建也会失败，您应将该请求视为一次原子性失败。

再举一个例子，首次向 AssetGroup 添加必需的资源时，请勿使用部分失败。您可以创建没有任何素材资源的素材资源组，也可以创建包含所有必需素材资源的素材资源组。首次向素材资源组添加素材资源时，您无法通过单独的请求一次添加一个素材资源。您必须将它们全部包含在一个请求中，并且不应使用部分失败。素材资源组包含所有必需的素材资源后，您可以一次添加或移除一个素材资源，这些请求可以使用部分失败。

如需确定部分失败是否合适，请检查是否需要在同一请求中进行跨操作资源引用时使用临时 ID。如果是这样，您就不应使用部分失败，因为第二个操作的成功与否取决于第一个操作的成功与否。

创建操作并进行 API 调用

按照常规方式创建 mutate 操作并进行 API 调用。

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

C#

private static MutateAdGroupsResponse CreateAdGroups(GoogleAdsClient client,
    long customerId, long campaignId)
{
    // Get the AdGroupServiceClient.
    AdGroupServiceClient adGroupService = client.GetService(Services.V25.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;
}

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