Google Ads API is returning to beta status. Please read our blog post for more details.

Usage flow

The steps for using batch processing are as follows:

1. Create a new mutate job

First, you need to create a MutateJob resource by calling CreateMutateJob.

PHP

private static function createMutateJob(
    MutateJobServiceClient $mutateJobServiceClient,
    int $customerId
) {
    $mutateJobResourceName =
        $mutateJobServiceClient->createMutateJob($customerId)->getResourceName();
    printf(
        "Created a mutate job with resource name: '%s'.%s",
        $mutateJobResourceName,
        PHP_EOL
    );
    return $mutateJobResourceName;
}

At this point in the process, the status of the job will be PENDING.

2. Add one or more mutate operations to the mutate job

Add one or more MutateOperation to the mutate job created in the previous step by calling AddMutateJobOperation. The response will contain:

  • The total number of operations added so far for this job
  • The sequence token to be used when calling this method again to add more operations

When you call AddMutateJobOperation again to add more operations, ensure you specify the previously obtained sequence token in the sequence_token field of a request. If you call the method using any sequence token other than the previously obtained one, it will result in an error.

sequence_token is also available as next_add_sequence_token of MutateJob, which you can retrieve later.

If you're creating dependent objects such as a complete campaign consisting of a new campaign and corresponding ad groups, ads, and keywords, you can use temporary IDs to specify a resource name.

PHP

private static function addAllMutateJobOperations(
    MutateJobServiceClient $mutateJobServiceClient,
    int $customerId,
    string $mutateJobResourceName
) {
    $response = $mutateJobServiceClient->addMutateJobOperations(
        $mutateJobResourceName,
        null,
        self::buildAllOperations($customerId)
    );
    printf(
        "%d mutate operations have been added so far.%s",
        $response->getTotalOperations(),
        PHP_EOL
    );
    // You can use this next sequence token for calling addMutateJobOperations() next time.
    printf(
        "Next sequence token for adding next operations is '%s'.%s",
        $response->getNextSequenceToken(),
        PHP_EOL
    );
}

See the content of buildAllOperations for each client library below:

3. Run the mutate job

After adding all your operations, you can request the Google Ads API to run the mutate job by calling RunMutateJob on the uploaded operations.

PHP

private static function runMutateJob(
    MutateJobServiceClient $mutateJobServiceClient,
    string $mutateJobResourceName
) {
    $operationResponse = $mutateJobServiceClient->runMutateJob($mutateJobResourceName);
    printf(
        "Mutate job with resource name '%s' has been executed.%s",
        $mutateJobResourceName,
        PHP_EOL
    );
    return $operationResponse;
}

The returned response will be an object of Operation (abbreviated as LRO). LRO contains the metadata of your mutate job along with the information about the job status.

4. Poll the status of the mutate job until it's done

The next step is to poll the status of the mutate job via LRO's GetOperation until the LRO's done is true.

PHP

private static function pollMutateJob(OperationResponse $operationResponse)
{
    $operationResponse->pollUntilComplete([
        'initialPollDelayMillis' => self::POLL_FREQUENCY_SECONDS * 1000,
        'totalPollTimeoutMillis' => self::MAX_TOTAL_POLL_INTERVAL_SECONDS * 1000
    ]);
}

5. List all mutate job results

When all your mutate jobs finish, you can list their results using ListMutateJobResults to print their statuses and responses:

PHP

private static function fetchAndPrintResults(
    MutateJobServiceClient $mutateJobServiceClient,
    string $mutateJobResourceName
) {
    printf(
        "Mutate job with resource name '%s' has finished. Now, printing its results...%s",
        $mutateJobResourceName,
        PHP_EOL
    );
    // Gets all the results from running mutate job and print their information.
    $mutateJobResults = $mutateJobServiceClient->listMutateJobResults(
        $mutateJobResourceName,
        ['pageSize' => self::PAGE_SIZE]
    );
    foreach ($mutateJobResults->iterateAllElements() as $mutateJobResult) {
        /** @var MutateJobResult $mutateJobResult */
        printf(
            "Mutate job #%d has a status '%s' and response of type '%s'.%s",
            $mutateJobResult->getOperationIndex(),
            $mutateJobResult->getStatus()
                ? $mutateJobResult->getStatus()->getMessage() : 'N/A',
            $mutateJobResult->getMutateOperationResponse()
                ? $mutateJobResult->getMutateOperationResponse()->getResponse()
                : 'N/A',
            PHP_EOL
        );
    }
}

The mutate_operation_response field will be null if a mutate job contains errors and cannot be completed.

The status field of MutateJobResult will contain all error details that might have caused the corresponding operation to fail.

Send feedback about...

Google Ads API Beta
Google Ads API Beta
Need help? Visit our support page.