Use the BulkMutateJobService to
schedule large batches of updates to your AdWords campaigns as
asynchronous bulk mutate jobs, and to retrieve the status, results
or statistics of your recent jobs.
For example, a single BulkMutateJob may contain mutate operations that update several ad-groups, create several ads, and add thousands of keywords.
Each customer has a single job queue - the jobs that operate on the customer are run one at a time in the order in which they were queued. Note: Jobs will be rejected (with an ApiException) once the customer has 10 pending jobs.
Call mutate with an ADD operation to create a new job containing the
first request part. The service will return the newly created job
with a BulkMutateJobId for referring to this job in future calls to the
service.
Call mutate with a SET operation for each additional request part
to be added to this job.
You may set BulkMutateJob.numRequestParts for the job during any of these
mutate requests. Failing to set this value will result in the job
remaining in its PENDING state
indefinitely.
Note: Both incomplete and queued jobs have a PENDING status, and so both count towards the
customer's pending job limit.
Mutate requests to the Bulk Mutate Job Service will fail if the request was invalid or if any of a job's structural constraints are violated, and depending on the operation, the job will not get created or updated.
Once a job has been submitted, you may check its status
periodically. When a job's status changes from PENDING to PROCESSING, you can request the job's processing
statistics to be included with the job's status if you need to
track the progress of the job.
Caution: Do not do poll the job status too frequently or you will risk getting your customer rate limited.
Once a job's status changes to COMPLETED, you can retrieve the job's results
one part at a time.
A job can fail even after it has been accepted for processing.
For example, a job may fail at this stage if the total number of
operations exceed the maximum limit for a job even though the
number of operations in each request part did not exceed the
maximum limit for a request part. If a job has a FAILED status it means that none of its mutate
operations were even processed.
Once a job is launched in the bulk mutate workflow, the operation streams in the job are sorted by scoping entity, which is either the customer or the parent campaign. The operations of a single scoping entity are always processed in their request order. Operations of different scoping entities may be processed concurrently or in a different order than in the request.
The operations for each scoping entity are processed in batches for efficiency. Each batch is processed atomically so that either all of them have successful results, or they all fail with a failure result for the entire batch.
The bulk mutate workflow will keep retrying operations when transient failures occur. However, if these failures persist for several hours or more serious ones occur, the bulk mutate workflow will abort a job leaving some or all of its operations unprocessed.
Returns a list of bulk mutate jobs.
| Field | Type | Description |
|---|---|---|
| selector |
BulkMutateJobSelector
|
Specifies which jobs to return. If the selector is empty, all jobs are returned. |
| Field | Type | Description |
|---|---|---|
| rval |
BulkMutateJob[]
|
List of bulk mutate jobs meeting the selector criteria. |
Adds or updates a bulk mutate job.
Use the «ADD» operator to submit a new job, and the «SET» operator to add additional request parts to an existing job. The «DELETE» operator is not supported.
Note: In the current implementation, the check for duplicate job keys is only "best effort", and may not prevent jobs with the same keys from being accepted if they are submitted around the same instant.
| Field | Type | Description |
|---|---|---|
| operation |
JobOperation
|
The operation to perform. |
| Field | Type | Description |
|---|---|---|
| rval |
BulkMutateJob
|
The added or updated bulk mutate job. |
|
