Nutzungsablauf

So verwenden Sie die Batchverarbeitung:

Neuen Batchjob erstellen

Rufen Sie MutateBatchJob auf, um eine BatchJob-Ressource zu erstellen. Wenn Sie das Objekt BatchJob erstellen, können Sie optional metadata.execution_limit_seconds auf eine positive Ganzzahl festlegen, um eine ungefähre Obergrenze in Sekunden zu konfigurieren, wie lange der Job ausgeführt werden kann, bevor er automatisch abgebrochen wird (siehe Zusätzliche Nutzungshinweise).

Java

private String createBatchJob(BatchJobServiceClient batchJobServiceClient, long customerId) {
  BatchJobOperation operation =
      BatchJobOperation.newBuilder().setCreate(BatchJob.newBuilder().build()).build();
  String batchJobResourceName =
      batchJobServiceClient
          .mutateBatchJob(Long.toString(customerId), operation)
          .getResult()
          .getResourceName();
  System.out.printf("Created a mutate job with resource name: '%s'.%n", batchJobResourceName);

  return batchJobResourceName;
}

C#

private static string CreateBatchJob(BatchJobServiceClient batchJobService,
    long customerId)
{
    BatchJobOperation operation = new BatchJobOperation()
    {
        Create = new BatchJob()
        {
        }
    };
    string batchJobResourceName =
        batchJobService.MutateBatchJob(customerId.ToString(), operation)
        .Result.ResourceName;
    Console.WriteLine($"Created a batch job with resource name: " +
        $"'{batchJobResourceName}'.");

    return batchJobResourceName;
}

PHP

private static function createBatchJob(
    BatchJobServiceClient $batchJobServiceClient,
    int $customerId
): string {
    // Creates a batch job operation to create a new batch job.
    $batchJobOperation = new BatchJobOperation();
    $batchJobOperation->setCreate(new BatchJob());

    // Issues a request to the API and get the batch job's resource name.
    $batchJobResourceName = $batchJobServiceClient->mutateBatchJob(
        MutateBatchJobRequest::build($customerId, $batchJobOperation)
    )->getResult()->getResourceName();
    printf(
        "Created a batch job with resource name: '%s'.%s",
        $batchJobResourceName,
        PHP_EOL
    );
    return $batchJobResourceName;
}

Python

def create_batch_job(
    batch_job_service: BatchJobServiceClient,
    customer_id: str,
    batch_job_operation: BatchJobOperation,
) -> str:
    """Creates a batch job for the specified customer ID.

    Args:
        batch_job_service: an instance of the BatchJobService message class.
        customer_id: a str of a customer ID.
        batch_job_operation: a BatchJobOperation instance set to "create"

    Returns: a str of a resource name for a batch job.
    """
    try:
        response: MutateBatchJobResponse = batch_job_service.mutate_batch_job(
            customer_id=customer_id, operation=batch_job_operation
        )
        resource_name: str = response.result.resource_name
        print(f'Created a batch job with resource name "{resource_name}"')
        return resource_name
    except GoogleAdsException as exception:
        handle_googleads_exception(exception)
        # This line will likely not be reached due to sys.exit(1) in handle_googleads_exception
        # but to satisfy the type checker, we add a return statement.
        return ""  # Or raise an exception

Ruby

def create_batch_job(client, batch_job_service, customer_id)
  # Creates a batch job operation to create a new batch job.
  operation = client.operation.create_resource.batch_job

  # Issues a request to the API and get the batch job's resource name.
  response = batch_job_service.mutate_batch_job(
    customer_id: customer_id,
    operation: operation
  )

  batch_job_resource_name = response.result.resource_name
  puts "Created a batch job with resource name: '#{batch_job_resource_name}'"

  batch_job_resource_name
end

Perl

sub create_batch_job {
  my ($batch_job_service, $customer_id) = @_;

  # Create a batch job operation.
  my $batch_job_operation =
    Google::Ads::GoogleAds::V26::Services::BatchJobService::BatchJobOperation->
    new({create => Google::Ads::GoogleAds::V26::Resources::BatchJob->new({})});

  my $batch_job_resource_name = $batch_job_service->mutate({
      customerId => $customer_id,
      operation  => $batch_job_operation
    })->{result}{resourceName};

  printf
    "Created a batch job with resource name: '%s'.\n",
    $batch_job_resource_name;

  return $batch_job_resource_name;
}

curl

# Creates a batch job.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   MANAGER_CUSTOMER_ID,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.

curl -f --request POST \
"https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/batchJobs:mutate" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data @- <<EOF
{
  "operation": {
    "create": {}
  }
}
EOF

An diesem Punkt im Prozess ist der status des Jobs PENDING.

Mutationsvorgänge zum Batchjob hinzufügen

Fügen Sie dem im vorherigen Schritt erstellten Batchjob ein oder mehrere MutateOperation-Objekte hinzu, indem Sie AddBatchJobOperations aufrufen. Die Antwort enthält dann Folgendes:

  • total_operations: Gesamtzahl der Vorgänge, die bisher für diesen Job hinzugefügt wurden.
  • next_sequence_token: Sequenztoken, das im Feld sequence_token übergeben werden soll, wenn Sie diese Methode noch einmal aufrufen, um weitere Vorgänge hinzuzufügen.

In der ersten AddBatchJobOperations-Anfrage für einen Batchjob muss sequence_token weggelassen werden. Wenn Sie AddBatchJobOperations noch einmal aufrufen, um weitere Vorgänge hinzuzufügen, geben Sie das zuvor abgerufene Sequenztoken im Feld sequence_token der Anfrage an. Wenn Sie die Methode mit einer leeren mutate_operations-Liste aufrufen, wird ein BatchJobError.EMPTY_OPERATIONS-Fehler zurückgegeben. Wenn Sie sie mit einem anderen Sequenztoken als dem zuvor abgerufenen aufrufen, wird ein BatchJobError.INVALID_SEQUENCE_TOKEN-Fehler zurückgegeben. Wenn Sie versuchen, Vorgänge nach dem Start des Jobs hinzuzufügen, wird ein BatchJobError.CANNOT_MODIFY_JOB_AFTER_JOB_STARTS_RUNNING-Fehler zurückgegeben.

Während der status des Batchjobs PENDING ist, ist sequence_token auch als next_add_sequence_token für die Ressource BatchJob verfügbar, die Sie später abrufen können.

Wenn Sie abhängige Objekte erstellen, z. B. eine vollständige Kampagne, die aus einer neuen Kampagne und entsprechenden Anzeigengruppen, Anzeigen und Keywords besteht, können Sie temporäre IDs verwenden, um einen Ressourcennamen anzugeben.

Java

private void addAllBatchJobOperations(
    BatchJobServiceClient batchJobServiceClient, long customerId, String batchJobResourceName) {
  AddBatchJobOperationsResponse response =
      batchJobServiceClient.addBatchJobOperations(
          AddBatchJobOperationsRequest.newBuilder()
              .setResourceName(batchJobResourceName)
              .addAllMutateOperations(buildAllOperations(customerId))
              .build());
  System.out.printf(
      "%d mutate operations have been added so far.%n", response.getTotalOperations());

  // You can use this next sequence token for calling addBatchJobOperations() next time.
  System.out.printf(
      "Next sequence token for adding next operations is '%s'.%n",
      response.getNextSequenceToken());
}

C#

private static void AddAllBatchJobOperations(BatchJobServiceClient batchJobService,
    long customerId, string batchJobResourceName)
{
    AddBatchJobOperationsResponse response =
        batchJobService.AddBatchJobOperations(
            new AddBatchJobOperationsRequest()
            {
                ResourceName = batchJobResourceName,
                MutateOperations = { BuildAllOperations(customerId) }
            });
    Console.WriteLine($"{response.TotalOperations} mutate operations have been added" +
        $" so far.");

    // You can use this next sequence token for calling AddBatchJobOperations() next time.
    Console.WriteLine($"Next sequence token for adding next operations is " +
        $"'{response.NextSequenceToken}'.");
}

PHP

private static function addAllBatchJobOperations(
    BatchJobServiceClient $batchJobServiceClient,
    int $customerId,
    string $batchJobResourceName
): void {
    $response = $batchJobServiceClient->addBatchJobOperations(
        AddBatchJobOperationsRequest::build(
            $batchJobResourceName,
            '',
            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 addBatchJobOperations() next time.
    printf(
        "Next sequence token for adding next operations is '%s'.%s",
        $response->getNextSequenceToken(),
        PHP_EOL
    );
}

Python

def add_all_batch_job_operations(
    batch_job_service: BatchJobServiceClient,
    operations: List[MutateOperation],
    resource_name: str,
) -> None:
    """Adds all mutate operations to the batch job.

    As this is the first time for this batch job, we pass null as a sequence
    token. The response will contain the next sequence token that we can use
    to upload more operations in the future.

    Args:
        batch_job_service: an instance of the BatchJobService message class.
        operations: a list of a mutate operations.
        resource_name: a str of a resource name for a batch job.
    """
    try:
        response: AddBatchJobOperationsResponse = (
            batch_job_service.add_batch_job_operations(
                resource_name=resource_name,
                sequence_token=None,  # type: ignore
                mutate_operations=operations,
            )
        )

        print(
            f"{response.total_operations} mutate operations have been "
            "added so far."
        )

        # You can use this next sequence token for calling
        # add_batch_job_operations() next time.
        print(
            "Next sequence token for adding next operations is "
            f"{response.next_sequence_token}"
        )
    except GoogleAdsException as exception:
        handle_googleads_exception(exception)

Ruby

def add_all_batch_job_operations(
  client,
  batch_job_service,
  customer_id,
  batch_job_resource_name)
  response = batch_job_service.add_batch_job_operations(
    resource_name: batch_job_resource_name,
    mutate_operations: build_all_operations(client, customer_id),
  )
  puts "#{response.total_operations} mutate operations have been added so far."

  # You can use this next sequence token for calling
  # add_all_batch_job_operations() next time
  puts "Next sequence token for adding next operations is " \
    "'#{response.next_sequence_token}'"
end

Perl

sub add_all_batch_job_operations {
  my ($batch_job_service, $customer_id, $batch_job_resource_name) = @_;

  my $add_batch_job_operations_response = $batch_job_service->add_operations({
      resourceName     => $batch_job_resource_name,
      sequenceToken    => undef,
      mutateOperations => build_all_operations($customer_id)});

  printf
    "%d batch operations have been added so far.\n",
    $add_batch_job_operations_response->{totalOperations};

  # You can use this next sequence token for calling add_operations() next time.
  printf
    "Next sequence token for adding next operations is '%s'.\n",
    $add_batch_job_operations_response->{nextSequenceToken};
}

curl

# Adds operations to a batch job.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   MANAGER_CUSTOMER_ID,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
#   BATCH_JOB_RESOURCE_NAME:
#     The resource name of the batch job to which the operations should be added
#     as returned by the previous step.

curl -f --request POST \
"https://googleads.googleapis.com/v${API_VERSION}/${BATCH_JOB_RESOURCE_NAME}:addOperations" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data @- <<EOF
{
  "mutateOperations": [
    {
      "campaignBudgetOperation": {
        "create": {
          "resourceName": "customers/${CUSTOMER_ID}/campaignBudgets/-1",
          "name": "batch job budget #${RANDOM}",
          "deliveryMethod": "STANDARD",
          "amountMicros": 5000000
        }
      }
    },
    {
      "campaignOperation": {
        "create": {
          "advertisingChannelType": "SEARCH",
          "status": "PAUSED",
          "name": "batch job campaign #${RANDOM}",
          "campaignBudget": "customers/${CUSTOMER_ID}/campaignBudgets/-1",
          "resourceName": "customers/${CUSTOMER_ID}/campaigns/-2",
          "manualCpc": {
          }
        }
      },
    }
  ]
}
EOF

Klicken Sie, um den Inhalt der Build-Vorgangsfunktion in GitHub für Ihre Clientbibliothek aufzurufen:

Batchjob ausführen

Nachdem Sie alle Vorgänge hinzugefügt haben, können Sie die Google Ads API auffordern, den Batchauftrag auszuführen. Dazu rufen Sie RunBatchJob für die hochgeladenen Vorgänge auf. Wenn Sie RunBatchJob aufrufen, nachdem der Job bereits gestartet wurde, wird der Fehler BatchJobError.CANNOT_MODIFY_JOB_AFTER_JOB_STARTS_RUNNING zurückgegeben.

Java

private OperationFuture runBatchJob(
    BatchJobServiceClient batchJobServiceClient, String batchJobResourceName) {
  OperationFuture operationResponse =
      batchJobServiceClient.runBatchJobAsync(batchJobResourceName);

  // BEWARE! The above call returns an OperationFuture. The execution of that future depends on
  // the thread pool which is owned by batchJobServiceClient. If you use this future, you *must*
  // keep the service client in scope too.
  // See https://developers.google.com/google-ads/api/docs/client-libs/java/lro for more detail.

  System.out.printf(
      "Mutate job with resource name '%s' has been executed.%n", batchJobResourceName);

  return operationResponse;
}

C#

private Operation<Empty, BatchJobMetadata> RunBatchJob(
    BatchJobServiceClient batchJobService, string batchJobResourceName)
{
    Operation<Empty, BatchJobMetadata> operationResponse =
        batchJobService.RunBatchJob(batchJobResourceName);
    Console.WriteLine($"Batch job with resource name '{batchJobResourceName}' has been " +
        $"executed.");

    return operationResponse;
}

PHP

private static function runBatchJob(
    BatchJobServiceClient $batchJobServiceClient,
    string $batchJobResourceName
): OperationResponse {
    $operationResponse =
        $batchJobServiceClient->runBatchJob(RunBatchJobRequest::build($batchJobResourceName));
    printf(
        "Batch job with resource name '%s' has been executed.%s",
        $batchJobResourceName,
        PHP_EOL
    );
    return $operationResponse;
}

Python

def run_batch_job(
    batch_job_service: BatchJobServiceClient, resource_name: str
) -> Operation:
    """Runs the batch job for executing all uploaded mutate operations.

    Args:
        batch_job_service: an instance of the BatchJobService message class.
        resource_name: a str of a resource name for a batch job.

    Returns: a google.api_core.operation.Operation instance.
    """
    try:
        response: Operation = batch_job_service.run_batch_job(
            resource_name=resource_name
        )
        print(
            f'Batch job with resource name "{resource_name}" has been '
            "executed."
        )
        return response
    except GoogleAdsException as exception:
        handle_googleads_exception(exception)
        # This line will likely not be reached due to sys.exit(1) in handle_googleads_exception
        # but to satisfy the type checker, we add a return statement.
        # In a real application, you might want to return a dummy Operation or raise an error.
        return Operation(
            op_type_name="type.googleapis.com/google.protobuf.Empty",
            complete=True,
            done_callbacks=[],
            metadata_type=None,
            result_type=None,
        )  # type: ignore

Ruby

def run_batch_job(batch_job_service, batch_job_resource_name)
  operation_response = batch_job_service.run_batch_job(
    resource_name: batch_job_resource_name,
  )
  puts "Batch job with resource name '#{batch_job_resource_name}' " \
    "has been executed."
  operation_response
end

Perl

sub run_batch_job {
  my ($batch_job_service, $batch_job_resource_name) = @_;

  my $batch_job_lro =
    $batch_job_service->run({resourceName => $batch_job_resource_name});

  printf
    "Batch job with resource name '%s' has been executed.\n",
    $batch_job_resource_name;

  return $batch_job_lro;
}

curl

# Runs a batch job.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   MANAGER_CUSTOMER_ID,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
#   BATCH_JOB_RESOURCE_NAME:
#     The resource name of the batch job to run as returned by the previous step.

curl -f --request POST \
"https://googleads.googleapis.com/v${API_VERSION}/${BATCH_JOB_RESOURCE_NAME}:run" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data @- <<EOF
{}
EOF

Die zurückgegebene Antwort ist ein lang andauerndes Operation-Objekt, das die Metadaten Ihres Batchjobs und Informationen zum Jobstatus enthält.

Status des Batchjobs abfragen, bis er abgeschlossen ist

Fragen Sie den Status des Batch-Jobs mit der Methode Operations.GetOperation im Dienst google.longrunning.Operations (getrennt von BatchJobService) ab, bis das Feld Operation.done den Wert true hat. In der Google Ads API ist Operations.GetOperation die einzige unterstützte Methode für google.longrunning.Operations (WaitOperation, ListOperations, CancelOperation und DeleteOperation geben UNIMPLEMENTED zurück):

  • Clientbibliotheken: Rufen Sie den Abfrage- oder Warte-Helper für den Wrapper des Vorgangs mit langer Ausführungszeit auf, der von RunBatchJob zurückgegeben wird. Alternativ können Sie den Vorgangsnamen an OperationService::poll_until_done in der REST-basierten Perl-Clientbibliothek übergeben. Dadurch wird Operations.GetOperation abgefragt, bis der Vorgang abgeschlossen ist oder das konfigurierte Abfrage-Zeitlimit abläuft. Prüfen Sie in Perl, ob done für den zurückgegebenen Hash true ist, bevor Sie die Ergebnisse auflisten. Lassen Sie in Java BatchJobServiceClient geöffnet, bis OperationFuture abgeschlossen ist.
  • REST: Senden Sie eine HTTP-GET-Anfrage an https://googleads.googleapis.com/v26/OPERATION_NAME (wobei OPERATION_NAME der Ressourcenname von Operation.name ist, formatiert als customers/CUSTOMER_ID/operations/OPERATION_ID) mit exponentiellem Backoff, bis das Feld Operation.done true ist.

Java

private void pollBatchJob(OperationFuture operationResponse) {
  try {
    operationResponse.get(MAX_TOTAL_POLL_INTERVAL_SECONDS, TimeUnit.SECONDS);
  } catch (InterruptedException | ExecutionException | TimeoutException e) {
    System.err.printf("Failed polling the mutate job. Exception: %s%n", e);
    System.exit(1);
  }
}

C#

private static void PollBatchJob(Operation<Empty, BatchJobMetadata> operationResponse)
{
    PollSettings pollSettings = new PollSettings(
        Expiration.FromTimeout(TimeSpan.FromSeconds(MAX_TOTAL_POLL_INTERVAL_SECONDS)),
        TimeSpan.FromSeconds(1));
    operationResponse.PollUntilCompleted(pollSettings);
}

PHP

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

Python

def poll_batch_job(
    operations_response: Operation, event: asyncio.Event
) -> None:
    """Polls the server until the batch job execution finishes.

    Sets the initial poll delay time and the total time to wait before time-out.

    Args:
        operations_response: a google.api_core.operation.Operation instance.
        event: an instance of asyncio.Event to invoke once the operations have
            completed, alerting the awaiting calling code that it can proceed.
    """
    loop: asyncio.AbstractEventLoop = asyncio.get_event_loop()

    def done_callback(future: Coroutine[Any, Any, Any]) -> None:
        # The operations_response object will call callbacks from a daemon
        # thread so we must use a threadsafe method of setting the event here
        # otherwise it will not trigger the awaiting code.
        loop.call_soon_threadsafe(event.set)

    # operations_response represents a Long-Running Operation or LRO. The class
    # provides an interface for polling the API to check when the operation is
    # complete. Below we use the asynchronous interface, but there's also a
    # synchronous interface that uses the Operation.result method.
    # See: https://googleapis.dev/python/google-api-core/latest/operation.html
    operations_response.add_done_callback(done_callback)  # type: ignore

Ruby

def poll_batch_job(operation_response)
  operation_response.wait_until_done!
end

Perl

sub poll_batch_job {
  my ($operation_service, $batch_job_lro) = @_;

  $operation_service->poll_until_done({
    name                 => $batch_job_lro->{name},
    pollFrequencySeconds => POLL_FREQUENCY_SECONDS,
    pollTimeoutSeconds   => POLL_TIMEOUT_SECONDS
  });
}

curl

# Gets the status of a batch job.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   MANAGER_CUSTOMER_ID,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
#   BATCH_JOB_OPERATION_NAME:
#     The operation name of the running batch job as returned by the previous
#     step.

curl -f --request GET \
"https://googleads.googleapis.com/v${API_VERSION}/${BATCH_JOB_OPERATION_NAME}" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \

Alternativ können Sie die Ressource batch_job mit der Methode GoogleAdsService.Search oder GoogleAdsService.SearchStream abfragen und dabei batch_job.status und bestimmte Unterfelder von BatchJobMetadata (z. B. batch_job.metadata.estimated_completion_ratio und batch_job.metadata.executed_operation_count) auswählen, bis batch_job.status den Wert DONE hat. Jede Operations.GetOperation- oder nicht paginierte GAQL-Anfrage zählt als ein Vorgang für Ihr tägliches API-Kontingent. Wenn Sie mehrere gleichzeitige Batchjobs überwachen, werden alle mit einer einzigen GAQL-Abfrage (WHERE batch_job.id IN (...) oder WHERE batch_job.status = 'RUNNING') in einer Anfrage geprüft, anstatt jeden Vorgang mit langer Ausführungszeit einzeln abzufragen.

Wenn Operation.done den Wert true hat, gibt der Vorgang mit langer Ausführungszeit eine leere Antwort ohne Fehler pro Vorgang zurück. Rufen Sie ListBatchJobResults auf, um die Ergebnisse einzelner Vorgänge zu prüfen.

Vorhandenen Vorgang mit langer Ausführungszeit abrufen

Wenn Ihre Anwendung Batchjobs von einem separaten Prozess abfragt oder die Abfrage nach einem Neustart fortsetzen muss, können Sie den Namen des Vorgangs mit langer Ausführungszeit mit GoogleAdsService.Search oder GoogleAdsService.SearchStream abrufen:

  1. Fragen Sie die Ressource batch_job ab, um das Feld long_running_operation zu lesen:

    SELECT
  batch_job.id,
  batch_job.status,
  batch_job.long_running_operation
FROM batch_job
WHERE batch_job.id = BATCH_JOB_ID

    Ersetzen Sie BATCH_JOB_ID durch die numerische ID des Batchjobs.

  2. Prüfen Sie, ob batch_job.status den Wert RUNNING oder DONE hat (long_running_operation ist nicht festgelegt, während der Job den Status PENDING hat, da kein Vorgang mit langer Ausführungszeit vorhanden ist, bis RunBatchJob aufgerufen wird). Lesen Sie den String long_running_operation aus dem zurückgegebenen BatchJob-Objekt.

  3. Fragen Sie den Vorgang mit dem String des Vorgangsnamens ab oder prüfen Sie ihn:

    • Clientbibliotheken: Rufen Sie den Operations-Client von Ihrem BatchJobService-Client ab (getOperationsClient() in Java und PHP, RunBatchJobOperationsClient in C#, transport.operations_client in Python, operations_client in Ruby oder $api_client->OperationService() in Perl), damit die Google Ads-Authentifizierung und die login-customer-id-Header automatisch konfiguriert werden, anstatt eine eigenständige OperationsClient zu instanziieren. Rufen Sie Operations.GetOperation (oder OperationService::get in Perl) für eine einzelne Statusprüfung auf oder verwenden Sie den Vorgangsnamen, um einen Wrapper für einen Vorgang mit langer Ausführungszeit fortzusetzen und bis zum Abschluss abzufragen (runBatchJobOperationCallable().resumeFutureCall in Java, PollOnceRunBatchJob in C#, resumeOperation in PHP, google.api_core.operation.from_gapic für das von get_operation in Python zurückgegebene Operation, wait_until_done! für das von get_operation in Ruby zurückgegebene Gapic::Operation oder name in OperationService::poll_until_done in Perl).
    • REST: Senden Sie eine HTTP-GET-Anfrage an https://googleads.googleapis.com/v26/OPERATION_NAME.

    Da OPERATION_NAME die API-Hauptversion codiert, in der die BatchJob erstellt wurde, schlägt Operations.GetOperation (auch über den aktiven REST-Endpunkt v26) mit dem Fehler RequestError.UNSUPPORTED_VERSION fehl, wenn diese Version inzwischen eingestellt wurde. Fragen Sie stattdessen batch_job.status direkt mit GoogleAdsService ab.

Vorgangsmetadaten verstehen

Wenn Sie den Vorgang mit langer Ausführungszeit abfragen oder die Ressource batch_job abfragen, liefert BatchJobMetadata Details zum Fortschritt des Batchjobs:

  • creation_date_time: Der Zeitstempel, der angibt, wann der Batchjob erstellt wurde.
  • start_date_time: Der Zeitstempel, der angibt, wann die Ausführung des Batchjobs gestartet wurde (wird ausgefüllt, wenn Sie batch_job.metadata.start_date_time mit GoogleAdsService abfragen; wird in RunBatchJob und Operations.GetOperation aus Operation.metadata weggelassen).
  • completion_date_time: Der Zeitstempel, der angibt, wann der Batchjob abgeschlossen wurde (nur vorhanden, wenn der Job abgeschlossen ist).
  • estimated_completion_ratio: Eine Schätzung des Anteils des Jobs (von 0,0 bis 1,0), der abgeschlossen wurde.
  • operation_count: Die Gesamtzahl der Vorgänge im Batchjob.
  • executed_operation_count: Die Anzahl der bisher ausgeführten Vorgänge.
  • execution_limit_seconds: Die ungefähre Obergrenze in Sekunden, wie lange der Batchjob ausgeführt werden kann, bevor er abgebrochen wird (wird ausgefüllt, wenn Sie batch_job.metadata.execution_limit_seconds mit GoogleAdsService abfragen, wenn bei der Joberstellung ein positives Limit festgelegt wurde; wird in RunBatchJob und Operations.GetOperation aus Operation.metadata weggelassen).

Diese Felder, insbesondere estimated_completion_ratio und die Anzahl der Vorgänge, können Ihnen helfen, den Fortschritt des Jobs zu beurteilen, die verbleibende Zeit zu schätzen und die Abrufhäufigkeit anzupassen. Beispielsweise könntest du seltener abfragen, wenn der estimated_completion_ratio niedrig ist, und häufiger, wenn er sich 1,0 nähert.

Alle Batchjob-Ergebnisse auflisten

Wenn der Batchjob abgeschlossen ist, rufen Sie ListBatchJobResults auf, um den Status und die Antwort für jeden Vorgang im Job abzurufen:

Java

private void fetchAndPrintResults(
    BatchJobServiceClient batchJobServiceClient, String batchJobResourceName) {
  System.out.printf(
      "Mutate job with resource name '%s' has finished. Now, printing its results...%n",
      batchJobResourceName);
  // Gets all the results from running mutate job and prints their information.
  ListBatchJobResultsPagedResponse batchJobResults =
      batchJobServiceClient.listBatchJobResults(
          ListBatchJobResultsRequest.newBuilder()
              .setResourceName(batchJobResourceName)
              .setPageSize(PAGE_SIZE)
              .build());
  for (BatchJobResult batchJobResult : batchJobResults.iterateAll()) {
    System.out.printf(
        "Mutate job #%d has a status '%s' and response of type '%s'.%n",
        batchJobResult.getOperationIndex(),
        batchJobResult.getStatus().getMessage().isEmpty()
            ? "N/A"
            : batchJobResult.getStatus().getMessage(),
        batchJobResult
                .getMutateOperationResponse()
                .getResponseCase()
                .equals(ResponseCase.RESPONSE_NOT_SET)
            ? "N/A"
            : batchJobResult.getMutateOperationResponse().getResponseCase());
  }
}

C#

private static void FetchAndPrintResults(BatchJobServiceClient batchJobService,
    string batchJobResourceName)
{
    Console.WriteLine($"batch job with resource name '{batchJobResourceName}' has " +
        $"finished. Now, printing its results...");

    ListBatchJobResultsRequest request = new ListBatchJobResultsRequest()
    {
        ResourceName = batchJobResourceName,
        PageSize = PAGE_SIZE,
    };
    ListBatchJobResultsResponse resp = new ListBatchJobResultsResponse();
    // Gets all the results from running batch job and prints their information.
    foreach (BatchJobResult batchJobResult in
        batchJobService.ListBatchJobResults(request))
    {
        if (!batchJobResult.IsFailed)
        {
            Console.WriteLine($"batch job result #{batchJobResult.OperationIndex} is " +
                $"successful and response is of type " +
                $"'{batchJobResult.MutateOperationResponse.ResponseCase}'.");
        }
        else
        {
            Console.WriteLine($"batch job result #{batchJobResult.OperationIndex} " +
                $"failed with error message {batchJobResult.Status.Message}.");

            foreach (GoogleAdsError error in batchJobResult.Failure.Errors)
            {
                Console.WriteLine($"Error found: {error}.");
            }
        }
    }
}

PHP

    private static function fetchAndPrintResults(
        BatchJobServiceClient $batchJobServiceClient,
        string $batchJobResourceName
    ): void {
        printf(
            "Batch job with resource name '%s' has finished. Now, printing its results...%s",
            $batchJobResourceName,
            PHP_EOL
        );
        // Gets all the results from running batch job and print their information.
        $batchJobResults = $batchJobServiceClient->listBatchJobResults(
            ListBatchJobResultsRequest::build($batchJobResourceName)->setPageSize(self::PAGE_SIZE)
        );
        foreach ($batchJobResults->iterateAllElements() as $batchJobResult) {
            /**
 * @var BatchJobResult $batchJobResult
*/
            printf(
                "Batch job #%d has a status '%s' and response of type '%s'.%s",
                $batchJobResult->getOperationIndex(),
                $batchJobResult->getStatus()
                    ? $batchJobResult->getStatus()->getMessage() : 'N/A',
                $batchJobResult->getMutateOperationResponse()
                    ? $batchJobResult->getMutateOperationResponse()->getResponse()
                    : 'N/A',
                PHP_EOL
            );
        }
    }

Python

def fetch_and_print_results(
    client: GoogleAdsClient,
    batch_job_service: BatchJobServiceClient,
    resource_name: str,
) -> None:
    """Prints all the results from running the batch job.

    Args:
        client: an initialized GoogleAdsClient instance.
        batch_job_service: an instance of the BatchJobService message class.
        resource_name: a str of a resource name for a batch job.
    """
    print(
        f'Batch job with resource name "{resource_name}" has finished. '
        "Now, printing its results..."
    )

    list_results_request: ListBatchJobResultsRequest = client.get_type(
        "ListBatchJobResultsRequest"
    )
    list_results_request.resource_name = resource_name
    list_results_request.page_size = 1000
    # Gets all the results from running batch job and prints their information.
    batch_job_results: ListBatchJobResultsResponse = (
        batch_job_service.list_batch_job_results(request=list_results_request)
    )

    for batch_job_result in batch_job_results:
        status: str = batch_job_result.status.message
        status = status if status else "N/A"
        result: Any = batch_job_result.mutate_operation_response
        result = result or "N/A"
        print(
            f"Batch job #{batch_job_result.operation_index} "
            f'has a status "{status}" and response type "{result}"'
        )

Ruby

def fetch_and_print_results(batch_job_service, batch_job_resource_name)
  puts "Batch job with resource name '#{batch_job_resource_name}' has " \
    "finished. Now, printing its results..." \

  # Gets all the results from running batch job and print their information.
  batch_job_results = batch_job_service.list_batch_job_results(
    resource_name: batch_job_resource_name,
    page_size: PAGE_SIZE,
  )
  batch_job_results.each do |result|
    puts "Batch job ##{result.operation_index} has a status " \
      "#{result.status ? result.status.message : 'N/A'} and response of type " \
      "#{result.mutate_operation_response ? result.mutate_operation_response.response : 'N/A'}"
  end
end

Perl

sub fetch_and_print_results {
  my ($batch_job_service, $batch_job_resource_name) = @_;

  printf "Batch job with resource name '%s' has finished. " .
    "Now, printing its results...\n", $batch_job_resource_name;

  # Get all the results from running batch job and print their information.
  my $list_batch_job_results_response = $batch_job_service->list_results({
    resourceName => $batch_job_resource_name,
    pageSize     => PAGE_SIZE
  });

  foreach my $batch_job_result (@{$list_batch_job_results_response->{results}})
  {
    printf
      "Batch job #%d has a status '%s' and response of type '%s'.\n",
      $batch_job_result->{operationIndex},
      $batch_job_result->{status} ? $batch_job_result->{status}{message}
      : "N/A",
      $batch_job_result->{mutateOperationResponse}
      ? [keys %{$batch_job_result->{mutateOperationResponse}}]->[0]
      : "N/A";
  }
}

curl

# Gets the results of a batch job.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   MANAGER_CUSTOMER_ID,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
#   BATCH_JOB_RESOURCE_NAME:
#     The operation name of the running batch job as returned by the previous
#     step.
curl -f --request GET \
"https://googleads.googleapis.com/v${API_VERSION}/${BATCH_JOB_RESOURCE_NAME}:listResults?pageSize=1000" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}"

In ListBatchJobResultsRequest wird das Feld page_size standardmäßig auf den Höchstwert von 1000 gesetzt, wenn es weggelassen oder auf 0 gesetzt wird. Wenn Sie page_size auf einen Wert größer als 1000 oder kleiner als 0 festlegen, wird ein BatchJobError.INVALID_PAGE_SIZE-Fehler zurückgegeben.

Jede BatchJobResult identifiziert den entsprechenden Vorgang mit operation_index, dem nullbasierten Index der hochgeladenen MutateOperation im Batchjob.

Batchjob abbrechen oder entfernen

Wie Sie einen Batchjob beenden oder verwerfen, hängt davon ab, ob RunBatchJob aufgerufen wurde:

Fehlerbehandlung

BatchJobService führt Standardvorgänge mit aktiviertem partiellem Fehler aus (erfolgreiche Vorgänge werden auch dann festgeschrieben, wenn andere Vorgänge im selben Job fehlschlagen, außer innerhalb von atomaren Unterbatches) und wiederholt automatisch Vorgänge, die aufgrund vorübergehender Fehler fehlschlagen. Es können jedoch nicht alle Fehlerszenarien vermieden werden. Vorgänge, die aufgrund von Validierungsfehlern fehlgeschlagen sind, können korrigiert und in einem neuen Batchjob noch einmal gesendet werden. Wenn ein Batchjob abgebrochen oder beendet wird, bevor alle Vorgänge abgeschlossen sind, können Sie die nicht ausgeführten Vorgänge (operation_index >= executed_operation_count) zusammen mit allen fehlgeschlagenen Vorgängen aus dem ausgeführten Präfix in einem neuen Batchjob noch einmal senden.

Zurück
Übersicht
Weiter
Temporäre IDs verwenden