Use temporary IDs

Page Summary

outlined_flag

• BatchJobService supports temporary IDs by specifying a negative ID for a new resource's resource_name.

• Temporary resource names can only be used after they are defined within the same job or mutate request and are not remembered across different jobs or requests.

• Each temporary resource name in a single job or mutate request must use a unique negative number, regardless of resource type.

• Referencing a new resource using its temporary ID in a later operation within the same request will automatically replace the temporary ID with the actual ID.

Temporary resource names

BatchJobService supports temporary resource names that can be referenced in subsequent operations within the same batch job—including across multiple sequential AddBatchJobOperations requests uploaded with a sequence_token. This lets you create a campaign and its dependent ad groups, ads, and criteria in a single batch job before server-side IDs are assigned. In the following general rules and example, a single request refers to an entire BatchJob across all of its AddBatchJobOperations uploads.

You can do this by specifying the new resource's resource_name to use a negative ID. For example, suppose you create a campaign and specify its resource name as customers/<YOUR_CUSTOMER_ID>/campaigns/-1. When you create the ad group in a later operation, you can then reference it by that resource name and the -1 you specified will be replaced by the actual ID of the created campaign automatically.

Here are some things to keep in mind when using temporary resource names:

• A temporary resource name can only be used after it's been defined in a resource. In the following example, the ad group operation would have to appear after the campaign operation in the list of operations.
• Temporary resource names are not remembered across jobs or mutate requests. To reference a resource created in a previous job or mutate request, use its actual resource name.
• For a single job or mutate request, each temporary resource name must use a unique negative number, even if they are from different resource types. If a temporary ID is reused in a single job or mutate request, then an error is returned.

Example

Suppose you want to add a campaign, an ad group, and an ad in a single API request. You would create a structure for your request analogous to the following:

mutate_operations: [
  {
    campaign_operation: {
      create: {
        resource_name: "customers/<YOUR_CUSTOMER_ID>/campaigns/-1",
        ...
      }
    }
  },
  {
    ad_group_operation: {
      create: {
        resource_name: "customers/<YOUR_CUSTOMER_ID>/adGroups/-2",
        campaign: "customers/<YOUR_CUSTOMER_ID>/campaigns/-1"
        ...
      }
    }
  },
  {
    ad_group_ad_operation: {
      create: {
        ad_group: "customers/<YOUR_CUSTOMER_ID>/adGroups/-2"
        ...
      }
    }
  },
]

A new temporary ID is used for the ad group, since we can't reuse the -1 that we used for the campaign. We also reference this ad group when creating an ad group ad. The ad group itself references the resource name we established for the campaign in an earlier operation in the request, while resource_name in ad_group_ad_operation is not necessary since no further operation is referencing it.

Error handling in batch jobs

Because standard operations in a batch job execute with partial failure enabled (except within atomic sub-batches), if a parent resource with a temporary ID fails validation, any dependent child operations referencing that temporary ID fail with NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. Reusing the same negative ID across multiple create operations within the same batch job returns NewResourceCreationError.DUPLICATE_TEMP_IDS. Temporary IDs are only valid when creating resources (create) or referencing newly created parent resources; for example, passing a negative temporary ID in AdGroupCriterionOperation.remove when calling AddBatchJobOperations returns RequestError.RESOURCE_NAME_MALFORMED.