If you want to perform a very large number of operations (up to 500,000) on your AdWords campaigns and child objects, use BulkMutateJobService to package them into a single asynchronous job that will process faster than a series of standard mutate operations. Also, unlike standard service-specific mutate operations, a single BulkMutateJob can operate against a mixed collection of campaigns, ad groups, ads, and criteria.
Each customer has a single job queue that can hold up to 10 bulk mutate jobs. Each job contains one or more parts, which are added one at a time (that is, one per SOAP request) to the job. When all parts of a job have been added, the job is automatically marked to run. Jobs are processed one at a time, in the order they are queued.
A bulk mutate job essentially consists of three types of objects, listed here from high- to low-level:
|
BulkMutateJob object itself, which stores information about job status, statistics, and results.BulkMutateRequest objects per job, each representing a single part of the job.OperationStream objects per BulkMutateRequest, each containing an array of operations within the scope of a single customer or campaign.mutate operations. The following types of operations are supported:
OperationStream object and set its fields:
operations contains the operations you want to performscopingEntityId describes the scope under which to perform these operations, and is used by the service to safely process operations. This ID can refer to either a campaign or a customer. Per BulkMutateJob, no more than 1 customer or 10 campaigns are allowed to be used as scoping entities.BulkMutateRequest object and set its fields:
operationStreams contains at least one OperationStream. No more than 25 OperationStream objects are allowed.partIndex describes which request part you are adding. For a new job, set this to 0. No more than 10,000 operations are allowed per BulkMutateRequest.BulkMutateJob object and set its fields:
request contains the BulkMutateRequest object you just made.numRequestParts defines the number of request parts this job shall contain. For smaller jobs, set this to 1. No more than 100 request parts are allowed.policy optionally defines conditions that must be met for this job to run.After you've constructed a BulkMutateJob, call mutate with the «ADD» operator to add it to the job queue. For larger jobs that require multiple request parts, you'll need to use additional mutate calls with the «SET» operator (one per additional request part) to add the remaining parts.
Caution: A job will not be considered for processing until the number of request parts submitted equals numRequestParts. Incomplete jobs remain indefinitely in the job queue and count against the maximum of 10 jobs per customer.
When a job begins, its status changes from «PENDING» to «PROCESSING». Unless the job encounters serious errors, its status will change to «COMPLETED» upon completion.
To retrieve existing jobs, use the get operation and a selector to specify which jobs to return:
jobIds retrieves jobs only with the specified IDsstatuses retrieves jobs only with the specified statusesresultPartIndex specifies which completed (result) part to retrieve. This field can be used only if jobIds selects a single completed job.Call get periodically to check the status of a processing bulk mutate job. When the job has completed, use calls to get with selector.resultPartIndex set from 0 to numRequestParts - 1 to retrieve the corresponding results for each BulkMutateRequest part.
Note: A completed job does not imply that all contained operations were successfully performed. The «COMPLETED» status only signifies that the job was able to finish.
Each BulkMutateResult part contains a list of OperationStreamResult objects; each OperationStreamResult contains a list of OperationResult objects.