Discover v2009: Asynchronous requests with the BulkMutateJobService

Wednesday, October 28, 2009


Delegation of tasks: we use this concept in our everyday lives when we pay someone to make us coffee, ask a colleague to take care of something while we run to the dentist, or tell our kids or younger siblings to handle a chore. What's common in all these situations? Well, you assign someone a task, possibly consisting of several parts, and then you wait for it to be completed. You can focus on other things while the task is being worked on, but you can still periodically ask what the status is (not too often, or they'll think you're annoying). Eventually they'll tell you it's done, and let you know whether it was successful or not. It's a simple process, and we intuitively know what to expect from it.

Well, you can now delegate complex tasks via the AdWords API! v2009 introduced a unified interface across all services for performing changes: the mutate method. This unification allowed us to develop the BulkMutateJobService, where you can provide a list of mutate operations to be performed for a number of different services, by scheduling a job which gets executed asynchronously. Much like the v13 ReportService, you can then poll for the job status, and once you get back the signal that it's been completed, you can ask for the results.

Let's dive into the details. BulkMutateJobs consist of the following:

  • BulkMutateRequests: these are the different parts of the job. The first one you submit should include a count of how many parts your job has; you submit one at a time, and once the last one is submitted, the job automatically starts. This helps build very large jobs, by avoiding the sending of a single, gigantic request.
  • OperationStreams: a BulkMutateRequest contains one or more OperationStreams, which can be executed in parallel (only in certain conditions, namely if their scopes target different campaigns).
  • Operations: each OperationStream contains a list of Operations, which are performed sequentially.
So to create a job with two parts, you would simply do:
BulkMutateJob job = new BulkMutateJob();
job.setNumRequestParts(2);
and fill in the details for the first part:
BulkMutateRequest part1 = new BulkMutateRequest();
part1.setPartIndex(0);
Then create an operation stream, consisting of several operations (they can even use different operators) and use it in the part:
OperationStream adStream = new OperationStream();
adStream.setScopingEntityId(scopingEntityId);
adStream.setOperations(new Operation[] {
new AdGroupAdOperation(Operator.ADD, null, adGroupAd1, null),
new AdGroupAdOperation(Operator.ADD, null, adGroupAd2, null)});
part1.setOperationStreams(new OperationStream[] {adStream});
Once we're done with that, we can create the JobOperation and submit the first part to the service:
JobOperation jobOperation = new JobOperation();
jobOperation.setOperand(job);
jobOperation.setOperator(Operator.ADD);
job = bulkMutateJobService.mutate(jobOperation);
Long jobId = job.getId();
Submitting the second part is similar, but now we must use the SET operator, since we're adding to an existing job, not creating a new one. Also, we must provide the job ID, so that the system knows which job we're submitting a new part for.
BulkMutateRequest part2 = new BulkMutateRequest();
part2.setPartIndex(1);
// ... OperationStream code goes here ...
job = new BulkMutateJob();
job.setId(jobId); // Here we set the ID to the one we got from
// the response to the first part

job.setRequest(part2);
job = bulkMutateJobService.mutate(new JobOperation(Operator.SET, null, job));
Once all the parts are submitted, the system automatically starts the job. Querying the status is easy, just perform a get with the job ID:
BulkMutateJobSelector selector = new BulkMutateJobSelector();
selector.setJobIds(new long[] {jobId});
BulkMutateJob[] jobs = bulkMutateJobService.get(selector);
job = jobs[0];
Don't query too often, though, or you may run trigger a rate-limiting protection! We recommend 30 seconds as a good value to wait between queries. Once the response comes back with a COMPLETED status, we can retrieve the results for both parts, by setting the resultPartIndex:
selector.setResultPartIndex(0);
jobs = bulkMutateJobService.get(selector);
job = jobs[0];
OperationResult[] operationResults1 =
job.getResult().getOperationStreamResults()[0].getOperationResults();

selector.setResultPartIndex(1);
jobs = bulkMutateJobService.get(selector);
job = jobs[0];
OperationResult[] operationResults2 =
job.getResult().getOperationStreamResults()[0].getOperationResults();
The BulkMutateResult object in the result field of the response includes a list of OperationStreamResults, which themselves are an array of OperationResults. Going through this hierarchy allows you to see which operations were successful and which ones failed, and act accordingly.

Note: If you're looking for a more complete example of using the BulkMutateJobService, please check the examples/demo folder in the client library of your choice. Also check Performing Bulk Jobs with BulkMutateJobService in the API documentation.

With the BulkMutateJobService you can provide as much work as possible to the API in one go and let it do its processing, without worrying about timeouts or broken connections. It won't affect your error handling, either, since the responses detail exactly what happened to all of the operations you performed. It's just an efficient way of getting a lot of work done in a single task. Come in and have a seat, the AdWords API is ready to take your order!

--Sérgio Gomes, AdWords API Team

This is the first of a series of posts on the exciting features of AdWords API v2009. In next week's edition of Discover v2009, we'll tell you all about getting ideas from the new TargetingIdeaService.

Happy Holidays! Enjoy more API units

Tuesday, October 27, 2009


We know the holiday season is a busy time for you and often means a number of updates to your campaigns. We'd once again like to help out by providing you with more API units.

Starting now and extending through January 15th of next year, all developers will receive a bonus of 20% more API units at no additional cost.

  • Developers can purchase API units at the rate of 1250/$0.25, up from 1000/$0.25
  • Advertisers who are eligible for free API units will receive credit at the rate 300/$ of AdWords spend, up from 250/$ of AdWords spend. They will be credited the holiday bonus based on their spend in previous months
You can view your API usage in your MCC account, by clicking the AdWords API Center link under the My Account tab.

As always, we encourage you to use the API as efficiently as possible. See our blog post on efficiency best practices to learn about ways to get more out of your API units. For more general API best practices, see our previous post dedicated to just that topic. Finally, we encourage developers to take advantage of the efficiencies and cost savings associated with API v2009.

Happy Holidays,
-Shreyas Doshi, Product Manager

AdWords API v200909 now available!

Thursday, October 22, 2009


We're happy to announce the newest version of AdWords API v2009! v200909 introduces several new features to the AdWords API; we've highlighted the main points below. For a complete list of the changes in v200909, please see our release notes.


v200909 Highlights
  • Asynchronous calls - Asynchronous calls allow you to work with large sets of data faster and more easily. Instead of having to wait for our system to fully complete your request before you can make another one, you’re now able to make another call as soon as the API service confirms that it has received your previous call. No more waiting for the server to complete large requests. V200909 will continue to support Synchronous methods as well.
  • Keyword and placement ideas - With the new TargetingIdeaService, you'll be able to get keyword and placement ideas through the API, leveraging the functionality of the search-based keyword tool.
  • Location Extensions preview - Limited location extensions functionality is now available as a preview of the full functionality in development.
Coming soon: Over the next few months, we'll continue to introduce new features and additional AdWords functionality. Upcoming features include ReportService, AccountService and the ability to pre-check for errors.

v13 Sunset in 2010:
With the release of equivalent functionality in v200909, the following v13 services will be sunset on April 22, 2010: CampaignService, AdGroupService, CriterionService, AdService, InfoService, KeywordToolService, SiteSuggestionService.

Given that v2009 introduces new concepts and features, we have extended the sunset period for deprecated services to 6 months. If you haven't already begun migrating your systems to the v2009 API, we strongly encourage you to start right away. The deprecation of remaining v13 services (AccountService, TrafficEstimatorService, and ReportService) and accompanying sunset dates will be announced on a future date.

As with every new version of the AdWords API, we encourage you to review the resources in the Developer's Guide to learn more. Additionally, if you aren't using the AdWords API client libraries yet, this is a good time to check them out as they are designed to work with both v2009 and v13.

Best,

Shreyas Doshi, Product Manager and Adam Wooley, Product Marketing Manager

AdWords Downtime: October 10th, 10am-2pm PDT

Tuesday, October 06, 2009


We'll be performing routine system maintenance on Saturday, October 10th from approximately 10:00am to 2:00pm PDT. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.

Best,
-Eric Koleda, AdWords API Team