Processing updates in bulk with MutateJobService

Processing updates in bulk with MutateJobService:

The AdWords API is designed to handle a high volume of changes, and many services allow developers to submit a large number of operations in one request. Most of the AdWords API services are synchronous though, so the client sends the request to the server, waits for processing and receives the result back.



Unlike other services, the MutateJobService (MJS) is designed for an asynchronous workflow. This has the following benefits:

• No need to manage connections for each job - the job is executed autonomously and the results can be retrieved when ready.
  
  
• Multiple jobs can be submitted and executed in parallel. In fact, the service has no limit on the maximum jobs count.
  
  
• Transient errors like 'CONCURRENT_MODIFICATION' are automatically retried with no extra requests necessary.
  
  
• Workload is automatically balanced so you will never receive a 'RateExceededError' error.
  
  

Also, MutateJobService operations cost only 50% of usual operations units cost.



Using MutateJobService in existing applications



Replacing existing calls to synchronous services with calls to MJS is easy. In most cases you can just use the same operations array to submit a job. Once submitted, the application needs to check the job status periodically to see when it is complete. Once ready, the results can be retrieved with the getResult method.



Please see examples in Java, PHP, Perl, DotNet, Ruby and Python for more details.



Recommendations:

• Don't poll for job status too often as this can result in RATE_EXCEEDED_ERROR error. We recommend pausing for 5-30 seconds between get requests.
  
  
• Although there is no minimum number of operations for a MJS job, it is more effective to send at least 100 operations per job. You can send up to 10,000 operations in one job.
  
  
• When submitting a job that operates on multiple AdGroups and Campaigns, try grouping operations in such a way as to minimize the number of different AdGroups in one job.
  
  

Note: while the old BulkMutateJobService is still available we recommend to use the MutateJobService for all future developments.



MutateJobService is covered in more details in our video presentation: Efficient API Usage with the MutateJobService. As always, please feel free to ask any questions regarding the AdWords API on our forum or during scheduled office hours.



- Danial Klimkin, AdWords API Team.