Use temporary IDs

  • 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.

To reference a newly created resource within the same mutate request or batch job, specify a negative integer ID (such as -1 or -2, excluding 0) in the new resource's resource_name field. For example, when creating a campaign in a batch request, set its resource name to customers/CUSTOMER_ID/campaigns/-1. When creating an ad group in a later operation within the same request, reference customers/CUSTOMER_ID/campaigns/-1 as the parent campaign. The API automatically replaces -1 with the actual campaign ID generated upon creation.

Usage constraints

Keep the following rules in mind when using temporary resource names:

  • Order matters: You can only reference a temporary resource name after you define it. In a list of operations, the dependent operation (such as creating an ad group) must appear after the operation that creates its parent resource (such as creating a campaign).
  • Single-request or batch-job scope: Temporary resource names do not persist across separate jobs or mutate requests. To reference a resource created in a previous job or mutate request, use its actual system-generated resource name.
  • Global uniqueness: Within a single job or mutate request, each temporary resource name must use a unique negative integer across all resource types. For example, you cannot assign -1 to both a campaign and an ad group in the same request. Reusing a temporary ID within the same request or batch job returns a NewResourceCreationError.DUPLICATE_TEMP_IDS error.

Example payload

Suppose you want to add a campaign, an ad group, and an ad in a single API request or batch job. You can structure the mutateOperations array in a GoogleAdsService.Mutate or BatchJobService.AddBatchJobOperations request payload as shown in the following REST JSON example (with other required resource fields omitted for brevity):

{
  "mutateOperations": [
    {
      "campaignOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/adGroups/-2",
          "campaign": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupAdOperation": {
        "create": {
          "adGroup": "customers/CUSTOMER_ID/adGroups/-2"
        }
      }
    }
  ]
}

This example demonstrates the following key details:

  • The ad group uses a new temporary ID (-2) because -1 is already assigned to the campaign.
  • The ad group references customers/CUSTOMER_ID/campaigns/-1 to link itself to the campaign created in the preceding operation.
  • The adGroupAdOperation references customers/CUSTOMER_ID/adGroups/-2 and omits resourceName because no subsequent operation in the request references the new ad.

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.

Previous
Usage flow
Next
Listing group filters