Fine grained partial failure in the BulkMutateJobService

Since its introduction the BulkMutateJobService has provided support for partial failures, allowing some operations to succeed even though others have failed. Over the next few weeks we'll be rolling out improvements to this functionality, allowing for more granular failures when possible.

Bulk mutate jobs process operations in batches, and a failed operation will cause the entire batch to fail, but not the rest of the job. The results for a failed batch start with a FailureResult that holds all the errors generated by the operations in that batch. It is followed by a series of BatchFailureResults which act as placeholders for the rest of the operations in the batch. More information about how these failures are reported can be found in a previous blog post we did on the topic.

In v201008 we enabled partial failure support for the synchronous AdGroupCriterionService. Unlike the behavior in the BulkMutateJobService, this version of partial failure allows individual operations to fail without affecting successful ones. This method of partial failure is preferred as it cuts down on the number of retries needed.

While we can't update the BulkMutateJobService to process all operations this way, we are able to enable it for operations that use an underlying service that does support granular partial failures. Starting August 1st, operations of type AdGroupCriterionOperation and AdGroupAdOperation processed by the BulkMutateJobService may start failing granularly instead of in batches.

Let's see how this will change the results returned.

Existing partial failure behavior

Operation	Result
AdGroupCriterionOperation	FailureResult cause.errors[0].fieldPath = "operations[1]..." cause.errors[1].fieldPath = "operations[2]..."
AdGroupCriterionOperation (Invalid)	BatchFailureResult operationIndexInBatch = 1
AdGroupCriterionOperation (Invalid)	BatchFailureResult operationIndexInBatch = 2
AdGroupCriterionOperation	BatchFailureResult operationIndexInBatch = 3

Before the change the invalid operations will cause other valid operations to fail. The FailureResult is the first result in the batch, even if the operation at the position was valid. The field path of the errors indicates the index of the invalid operations relative to the start of the batch.

New granular partial failure behavior

Operation	Result
AdGroupCriterionOperation	ReturnValueResult
AdGroupCriterionOperation (Invalid)	FailureResult cause.errors[0].fieldPath = "operations[0]..."
AdGroupCriterionOperation (Invalid)	FailureResult cause.errors[0].fieldPath = "operations[0]..."
AdGroupCriterionOperation	ReturnValueResult

After the change invalid operations will not affect other valid operations in the same batch. Each invalid operation will have a corresponding FailureResult. There may still be cases where BatchFailureResults are returned for these operations, such as if there is a general error with the account that cannot be attributed to any specific operation.

So how does this affect code you've already written to process BulkMutateJob results? The good news is that if you've written your code to allow for a variable batch size (no hard coded batch size) then no changes are needed! Invalid operations are essentially processed as batches of one, and the same logic that you use to process the results today should work perfectly with these new granular failures. If your application is currently expecting a batch of a specific size then you should update it to detect the start and end of batches dynamically.

If you have any questions about how these new granular failures work, or feedback on how we can further improve the error handling in the API, add a post to the AdWords API forum.

Update 2011-08-25
This change has been fully deployed and all BulkMutateJobs will be processed with granular partial failures enabled.

- Eric Koleda, AdWords API Team

Discover v201101: Experiment Reports

Back in September of 2010, we added support to manage AdWords Campaign Experiments (ACE) via the API. With the release of v201101, we are extending the API to allow you to fully manage your experiments, as we’ve included new experiment fields for use in reports. You can now segment your report statistics by the experiment splits as well as obtain experiment statistical significance on every statistical field (i.e. clicks, impressions, conversions, etc).

Segmentation

A new field called AdvertiserExperimentSegmentationBin is now available for you to segment your report rows in OUTSIDE_OF_EXPERIMENT, CONTROL and EXPERIMENT. Rows reported as OUTSIDE_OF_EXPERIMENT refer to statistics captured outside the experiment lifespan, which will occur when your report dateRange covers a broader time period than your experiment. Data reported as part of the CONTROL segment includes statistical values that belong to the percentage of traffic that you have configured as part of your control split. Likewise, values for the experimental split are reported with the EXPERIMENT value.

Keep in mind that adding AdvertiserExperimentSegmentationBin to your reports may potentially multiply their size by three, so make sure you use report predicates to control exactly what you want back and to define your reports in one of the GZIP compressed formats, if possible.

Statistical Significance

For every available statistical field (i.e. Clicks, Impressions, Conversions, CPC, CPM, etc) a Statistical Significance field pair is now available for you to use in some reports. These new field pairs have, with a few exceptions, the form of [field singular name]Significance, so for example Clicks has ClickSignificance as its pair. For more information about the available Statistical Significance fields per report see our Report Types page.

Significance fields have a specific range of values that goes from -3 to 3, values that correspond to three
, two and one (down and up) arrows respectively in the AdWords interface, while 0 is represented by a grayed up and down arrow.  To learn more about  Statistical Significance and its meaning visit our Help Center FAQ page. Also keep in mind that negative values don’t mean your experiment isn’t going as expected since fields that imply cost, like CPC, you most likely want to have a negative variation.

Life of your experiment data

Your experiment segmented statistics will exist as long as your experiment does, so as soon as your experiment is either promoted or deleted you will no longer able to retrieve experiment statistics. Hence, we recommend you download a last set of experiment reports right before the experiment gets promoted or deleted.

Reports Types Included

AdWords Campaign Experiments are applied at the Campaign level, therefore reports that apply to Campaigns, AdGroups, Ads and Keywords have included experiment specific fields. Specifically, the following reports have been enhanced with experiment fields: Ad Performance, Ad Group Performance, Campaign Performance, Keyword Performance and Managed Placements Performance.

As always, feel free to contact us at the AdWords API Forum.

- David Torres, AdWords API Team

Client Library Updates

We often make changes to the AdWords API client libraries that do not merit a full blog post. We’d like to start publishing a summary blog post every other week to highlight changes that might otherwise go unnoticed.

Python

• Added support for OAuth as an authentication mechanism. This will allow developers to access the API without requiring a username and password. See the new code example for more information on how to integrate OAuth with your application.
• Additionally, a number of issues were fixed: 115, 142, 144, and 145.

Perl

• Fixed some bugs that prevented usage of multiple Client objects.
• Full XPath support was added; XPath queries can now be done through the entire tree of results.
• OAuth support was also added.

Ruby

• Improved support for UTF reports in download extensions.
• New logger interface.
• Updates have been made to the code examples.

PHP

• Updated OAuth support to allow for alternative OAuth libraries, including the bundled Andy Smith library.
• The logging functionality has been updated to support filtering for levels. The default logging behavior has been changed to only log SOAP XML if an error occurs.
• New methods were added to AdWordsUser for additional logging configuration. The AdWords Get*Service() methods were replaced with a single GetService() method. Backwards compatibility was maintained using __call(). All examples and tests were updated to use the new method.
• Additionally, 2 issues were fixed: 55 and 59.

You can download updated versions of the AdWords API client libraries from their respective sites, or see a list of all the client libraries using this link.

If you have any questions or would like to discuss these changes, please post on the forum.

Kevin Winter, AdWords API Team