זרימת שימוש

כדי להשתמש בעיבוד באצווה:

יצירת משימה באצווה חדשה

כדי ליצור משאב BatchJob, מתקשרים אל MutateBatchJob. כשיוצרים את האובייקט BatchJob, אפשר להגדיר את metadata.execution_limit_seconds כדי לקבוע את משך הזמן המקסימלי, בשניות, שבו העבודה יכולה לפעול לפני שהיא מבוטלת אוטומטית (ראו הנחיות נוספות לשימוש).

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;
}
AddCompleteCampaignsUsingBatchJob.java
      

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;
}
AddCompleteCampaignsUsingBatchJob.cs
      

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;
}
AddCompleteCampaignsUsingBatchJob.php
      

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
add_complete_campaigns_using_batch_job.py
      

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
add_complete_campaigns_using_batch_job.rb
      

Perl

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

  # Create a batch job operation.
  my $batch_job_operation =
    Google::Ads::GoogleAds::V25::Services::BatchJobService::BatchJobOperation->
    new({create => Google::Ads::GoogleAds::V25::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;
}
add_complete_campaigns_using_batch_job.pl
      

curl

# Creates a batch job.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   DEVELOPER_TOKEN,
#   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 "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data @- <<EOF
{
  "operation": {
    "create": {}
  }
}
EOF
add_complete_campaigns_using_batch_job.sh
      

בשלב הזה בתהליך, status המשרה הוא PENDING.

הוספת פעולות שינוי למשימה באצווה

מוסיפים אובייקט MutateOperation אחד או יותר למשימת האצווה שנוצרה בשלב הקודם על ידי קריאה ל-AddBatchJobOperations. התשובה מכילה את הפרטים הבאים:

• ‫total_operations: המספר הכולל של הפעולות שנוספו עד עכשיו למשימה הזו.
• ‫next_sequence_token: אסימון רצף שמעבירים בשדה sequence_token כשקוראים שוב לשיטה הזו כדי להוסיף עוד פעולות.

בבקשה הראשונה של AddBatchJobOperations לעיבוד אצווה, צריך להשמיט את sequence_token. כשמפעילים את הפונקציה AddBatchJobOperations שוב כדי להוסיף עוד פעולות, צריך לציין את אסימון הרצף שהתקבל קודם בשדה sequence_token של הבקשה. הפעלת ה-method עם רשימה ריקה של mutate_operations מחזירה שגיאה מסוג BatchJobError.EMPTY_OPERATIONS, הפעלת ה-method עם אסימון רצף כלשהו ששונה מהאסימון שהתקבל קודם מחזירה שגיאה מסוג BatchJobError.INVALID_SEQUENCE_TOKEN, וניסיון להוסיף פעולות אחרי שהריצה של העבודה מתחילה מחזיר שגיאה מסוג BatchJobError.CANNOT_MODIFY_JOB_AFTER_JOB_STARTS_RUNNING.

בזמן שהערך של status במשימת האצווה הוא PENDING, הערך של sequence_token זמין גם כ-next_add_sequence_token במשאב BatchJob, שאפשר לאחזר אותו מאוחר יותר.

אם אתם יוצרים אובייקטים תלויים, כמו קמפיין שלם שמורכב מקמפיין חדש ומקבוצות מודעות, מודעות ומילות מפתח תואמות, אתם יכולים להשתמש במזהים זמניים כדי לציין שם של משאב.

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());
}
AddCompleteCampaignsUsingBatchJob.java
      

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}'.");
}
AddCompleteCampaignsUsingBatchJob.cs
      

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
    );
}
AddCompleteCampaignsUsingBatchJob.php
      

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)
add_complete_campaigns_using_batch_job.py
      

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
add_complete_campaigns_using_batch_job.rb
      

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};
}
add_complete_campaigns_using_batch_job.pl
      

curl

# Adds operations to a batch job.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   DEVELOPER_TOKEN,
#   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 "developer-token: ${DEVELOPER_TOKEN}" \
--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
add_complete_campaigns_using_batch_job.sh
      

לוחצים כדי לראות את התוכן של פונקציית פעולות ה-build ב-GitHub עבור ספריית הלקוח:

Java

buildAllOperations()

C#‎

BuildAllOperations()

PHP

buildAllOperations()

Python

build_all_operations()

Ruby

build_all_operations()

Perl

build_all_operations

טיפ: לסדר הפעולות יכולה להיות השפעה משמעותית על הביצועים של העבודה. כדאי לעיין בטיפ בנושא סדר הפעולות במאמר שיטות מומלצות.

הרצת משימה באצווה

אחרי שמוסיפים את כל הפעולות, אפשר לבקש מ-Google Ads API להריץ את העבודה באצווה על ידי קריאה ל-RunBatchJob בפעולות שהועלו. קריאה אל RunBatchJob אחרי שהריצה של העבודה כבר התחילה מחזירה שגיאה BatchJobError.CANNOT_MODIFY_JOB_AFTER_JOB_STARTS_RUNNING.

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;
}
AddCompleteCampaignsUsingBatchJob.java
      

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;
}
AddCompleteCampaignsUsingBatchJob.cs
      

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;
}
AddCompleteCampaignsUsingBatchJob.php
      

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
add_complete_campaigns_using_batch_job.py
      

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
add_complete_campaigns_using_batch_job.rb
      

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;
}
add_complete_campaigns_using_batch_job.pl
      

curl

# Runs a batch job.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   DEVELOPER_TOKEN,
#   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/v19/${BATCH_JOB_RESOURCE_NAME}:run" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data @- <<EOF
{}
EOF
add_complete_campaigns_using_batch_job.sh
      

התגובה שמוחזרת היא אובייקט long-running Operation (LRO). ה-LRO מכיל את המטא-נתונים של משימה באצווה, יחד עם המידע על סטטוס המשימה.

שליחת שאילתות לגבי הסטטוס של משימה באצווה עד שהיא מסתיימת

השלב הבא הוא לדגום את הסטטוס של משימה באצווה באמצעות GetOperation של LRO עד שהערך של done של LRO יהיה true.

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);
  }
}
AddCompleteCampaignsUsingBatchJob.java
      

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);
}
AddCompleteCampaignsUsingBatchJob.cs
      

PHP

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

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
add_complete_campaigns_using_batch_job.py
      

Ruby

def poll_batch_job(operation_response)
  operation_response.wait_until_done!
end
add_complete_campaigns_using_batch_job.rb
      

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
  });
}
add_complete_campaigns_using_batch_job.pl
      

curl

# Gets the status of a batch job.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   DEVELOPER_TOKEN,
#   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 "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
add_complete_campaigns_using_batch_job.sh
      

אחזור של פעולה ממושכת קיימת

אם האפליקציה שלכם מבצעת שאילתות לגבי משימות אצווה מתהליך נפרד או צריכה להמשיך לבצע שאילתות אחרי הפעלה מחדש, אתם יכולים לאחזר את שם הפעולה הממושכת באמצעות GoogleAdsService.Search או GoogleAdsService.SearchStream:

1. מריצים שאילתה על המשאב batch_job כדי לקרוא את השדה long_running_operation:

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

2. מוודאים שהערך של batch_job.status הוא RUNNING או DONE (הערך של long_running_operation מאוכלס רק אחרי שקוראים ל-RunBatchJob, והוא לא מוגדר בזמן שהעבודה היא PENDING), וקוראים את המחרוזת long_running_operation מהאובייקט BatchJob שמוחזר.

3. מעבירים את המחרוזת של שם הפעולה אל GetOperation ב-OperationsClient של ספריית הלקוח כדי לבדוק או להמשיך את הסקר של Operation.

הסבר על מטא-נתונים של פעולות

כשמבצעים דגימה של פעולה ממושכת, השדה metadata בתשובה Operation מספק פרטים נוספים על התקדמות העבודה של העיבוד באצווה. השדה הזה מכיל אובייקט BatchJobMetadata. בין תחומי המשנה העיקריים:

• ‫creation_date_time: חותמת הזמן שבה נוצרה משימת האצווה.
• ‫start_date_time: חותמת הזמן שבה התחילה ההרצה של משימה באצווה.
• ‫completion_date_time: חותמת הזמן שבה הסתיימה משימת האצווה (מופיעה רק אם המשימה הסתיימה).
• ‫estimated_completion_ratio: אומדן של החלק היחסי של המשימה שהושלמה (בין 0.0 ל-1.0).
• ‫operation_count: המספר הכולל של הפעולות במשימת האצווה.
• ‫executed_operation_count: מספר הפעולות שבוצעו עד עכשיו.
• ‫execution_limit_seconds: הגבול העליון המשוער, בשניות, למשך הזמן שבו אפשר להריץ את משימת האצווה לפני שהיא תבוטל.

השדות האלה, במיוחד estimated_completion_ratio ומספר הפעולות, יכולים לעזור לכם להעריך את התקדמות העבודה, להעריך את הזמן שנותר ולשנות את תדירות הבדיקה. לדוגמה, אפשר לבצע סקר בתדירות נמוכה יותר כשהערך של estimated_completion_ratio נמוך, ובתדירות גבוהה יותר כשהוא מתקרב ל-1.0.

הצגת כל התוצאות של משימות אצווה

כשכל העבודות באצווה מסתיימות, משתמשים בפקודה ListBatchJobResults כדי להציג את התוצאות שלהן, ומדפיסים את הסטטוסים והתשובות שלהן:

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());
  }
}
AddCompleteCampaignsUsingBatchJob.java
      

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}.");
            }
        }
    }
}
AddCompleteCampaignsUsingBatchJob.cs
      

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
            );
        }
    }
AddCompleteCampaignsUsingBatchJob.php
      

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}"'
        )
add_complete_campaigns_using_batch_job.py
      

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
add_complete_campaigns_using_batch_job.rb
      

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";
  }
}
add_complete_campaigns_using_batch_job.pl
      

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}"
add_complete_campaigns_using_batch_job.sh
      

ב-ListBatchJobResultsRequest, ערך ברירת המחדל של השדה page_size הוא הערך המקסימלי 1000 אם הוא לא מצוין או אם הוא מוגדר כ-0. הגדרת page_size לערך שגדול מ-1000 או קטן מ-0 מחזירה שגיאה BatchJobError.INVALID_PAGE_SIZE.

כל BatchJobResult מזהה את הפעולה המתאימה באמצעות operation_index, שהוא האינדקס מבוסס-0 של MutateOperation שהועלה בעבודת האצווה.

• פעולה מוצלחת: השדה mutate_operation_response מאוכלס (השדה response שלו מכיל את resource_name של המשאב שעבר שינוי, בתוספת כל השדות שניתנים לשינוי אם השדה response_content_type מוגדר ל-MUTABLE_RESOURCE), והשדה status לא מוגדר.
• פעולה שנכשלה (או שלא בוצעה): הערך של mutate_operation_response לא מוגדר, ו- status מכיל את פרטי השגיאה של הפעולה.

נקודה חשובה: אם קוראים לפונקציה ListBatchJobResults לפני שקוראים לפונקציה RunBatchJob או לפני שמשימת האצווה מסתיימת, מוחזרת שגיאה BatchJobError.RESULTS_NOT_READY. אם שגיאות לא צפויות בנקודת הבדיקה של השרת מונעות את הצגת התוצאות של משימת האצווה, מוחזרת שגיאה BatchJobError.CANNOT_LIST_RESULTS.

ביטול או הסרה של משימה באצווה

הדרך להפסיק או לבטל עבודת אצווה תלויה בשאלה אם בוצעה קריאה ל-RunBatchJob:

• לפני שמתקשרים אל RunBatchJob: בזמן שהסטטוס של העבודה status הוא PENDING, אפשר לבטל את משימת האצווה על ידי קריאה אל MutateBatchJob עם BatchJobOperation.remove. התקשרות אל remove אחרי שהעבודה מתחילה לפעול מחזירה שגיאה BatchJobError.CAN_ONLY_REMOVE_PENDING_JOB.
• אחרי הקריאה ל-RunBatchJob: אחרי שנוצרת פעולה ממושכת, אפשר לנסות לבטל את משימת האצווה הפעילה על ידי קריאה ל-CancelOperation בפעולה הממושכת. מכיוון שפעולות רגילות ב משימה באצווה מבוצעות עם האפשרות partial failure (פעולות בatomic sub-batches מבוטלות יחד), ביטול של משימה באצווה לא מבטל פעולות שכבר הושלמו לפני שהביטול נכנס לתוקף. אחרי שהסטטוס של משימה שבוטלה (או שהופסקה) status משתנה לסטטוס DONE, קריאה ל-ListBatchJobResults מחזירה רשומות של BatchJobResult עבור הקידומת שהופעלה (operation_index < executed_operation_count) עם תוצאות ההפעלה האישיות שלהן, ואחריהן רשומות של BatchJobResult עבור כל הפעולות הנותרות שלא הופעלו (operation_index מ-executed_operation_count עד operation_count - 1) עם mutate_operation_response לא מוגדר ו-status מאוכלס בסטטוס השגיאה ברמת המשימה (או InternalError.INTERNAL_ERROR).

טיפול בשגיאות

‫BatchJobService מבצע פעולות רגילות עם האפשרות partial failure (כשל חלקי) מופעלת (פעולות מוצלחות מתבצעות גם אם פעולות אחרות באותה משימה נכשלות, למעט בתוך atomic sub-batches) ומנסה לבצע מחדש באופן אוטומטי פעולות שנכשלות בגלל שגיאות זמניות. עם זאת, אי אפשר להימנע מכל תרחישי הכשל. אפשר לתקן פעולות שנכשלו בגלל שגיאות אימות ולשלוח אותן מחדש במשימה באצווה חדשה. באופן דומה, אם משימה באצווה מבוטלת או מופסקת לפני השלמת כל הפעולות, אפשר לשלוח מחדש את הפעולות שלא בוצעו (operation_index >= executed_operation_count) יחד עם כל הפעולות שנכשלו מהתחילית שהופעלה במשימה באצווה חדשה.