Usar IDs temporales

Nombres de recursos temporales

BatchJobService admite nombres de recursos temporales a los que se puede hacer referencia en operaciones posteriores dentro del mismo trabajo por lotes, incluso en varias solicitudes secuenciales AddBatchJobOperations subidas con un sequence_token. Esto te permite crear una campaña y sus grupos de anuncios, anuncios y criterios dependientes en un solo trabajo por lotes antes de que se asignen los IDs del servidor. En las siguientes reglas generales y en el ejemplo, una sola solicitud se refiere a un BatchJob completo en todas sus cargas de AddBatchJobOperations.

Para hacer referencia a un recurso recién creado dentro de la misma solicitud de mutación o trabajo por lotes, especifica un ID de número entero negativo (como -1 o -2, sin incluir 0) en el campo resource_name del recurso nuevo. Por ejemplo, cuando crees una campaña en una solicitud por lotes, establece su nombre de recurso en customers/CUSTOMER_ID/campaigns/-1. Cuando crees un grupo de anuncios en una operación posterior dentro de la misma solicitud, haz referencia a customers/CUSTOMER_ID/campaigns/-1 como la campaña superior. La API reemplaza automáticamente -1 por el ID de campaña real que se genera cuando se crea.

Restricciones de uso

Ten en cuenta las siguientes reglas cuando uses nombres de recursos temporales:

• El orden es importante: Solo puedes hacer referencia a un nombre de recurso temporal después de definirlo. En una lista de operaciones, la operación dependiente (como la creación de un grupo de anuncios) debe aparecer después de la operación que crea su recurso superior (como la creación de una campaña).
• Alcance de la solicitud única o del trabajo por lotes: Los nombres de recursos temporales no persisten en trabajos separados ni en solicitudes de mutación. Para hacer referencia a un recurso creado en un trabajo anterior o en una solicitud de mutación, usa su nombre de recurso real generado por el sistema.
• Unicidad global: Dentro de un solo trabajo o solicitud de mutación, cada nombre de recurso temporal debe usar un número entero negativo único en todos los tipos de recursos. Por ejemplo, no puedes asignar -1 a una campaña y a un grupo de anuncios en la misma solicitud. Si vuelves a usar un ID temporal dentro de la misma solicitud o trabajo por lotes, se muestra un error NewResourceCreationError.DUPLICATE_TEMP_IDS.

Ejemplo de carga útil

Supongamos que deseas agregar una campaña, un grupo de anuncios y un anuncio en una sola solicitud a la API o trabajo por lotes. Puedes estructurar el array mutateOperations en una carga útil de solicitud GoogleAdsService.Mutate o BatchJobService.AddBatchJobOperations como se muestra en el siguiente ejemplo de JSON de REST (con otros campos de recursos obligatorios omitidos para mayor brevedad):

{
  "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"
        }
      }
    }
  ]
}

En este ejemplo, se muestran los siguientes detalles clave:

• El grupo de anuncios usa un nuevo ID temporal (-2) porque -1 ya está asignado a la campaña.
• El grupo de anuncios hace referencia a customers/CUSTOMER_ID/campaigns/-1 para vincularse a la campaña creada en la operación anterior.
• adGroupAdOperation hace referencia a customers/CUSTOMER_ID/adGroups/-2 y omite resourceName porque ninguna operación posterior en la solicitud hace referencia al anuncio nuevo.

Manejo de errores en trabajos por lotes

Dado que las operaciones estándar en un trabajo por lotes se ejecutan con la falla parcial habilitada (excepto dentro de los sub-lotes atómicos), si un recurso superior con un ID temporal no pasa la validación, cualquier operación secundaria dependiente que haga referencia a ese ID temporal fallará con NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. Si vuelves a usar el mismo ID negativo en varias operaciones create dentro del mismo trabajo por lotes, se muestra NewResourceCreationError.DUPLICATE_TEMP_IDS. Los IDs temporales solo son válidos cuando se crean recursos (create) o se hace referencia a recursos superiores recién creados. Por ejemplo, si se pasa un ID temporal negativo en AdGroupCriterionOperation.remove cuando se llama a AddBatchJobOperations, se muestra RequestError.RESOURCE_NAME_MALFORMED.