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 AddBatchJobOperations secuenciales que se suben 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 el ejemplo, una sola solicitud hace referencia 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 del 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 principal. La API reemplaza automáticamente -1 por el ID de campaña real que se genera en el momento de la creación.

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 principal (como la creación de una campaña).
• Alcance de solicitud única o trabajo por lotes: Los nombres de recursos temporales no persisten entre trabajos separados ni solicitudes de mutación. Para hacer referencia a un recurso creado en un trabajo o una solicitud de modificación anteriores, 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 se vuelve a usar un ID temporal en la misma solicitud o trabajo por lotes, se devuelve 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 de 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 sublotes atómicos), si un recurso principal con un ID temporal no supera la validación, cualquier operación secundaria dependiente que haga referencia a ese ID temporal fallará con NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. Si se reutiliza el mismo ID negativo en varias operaciones de create dentro del mismo trabajo por lotes, se devuelve NewResourceCreationError.DUPLICATE_TEMP_IDS. Los IDs temporales solo son válidos cuando se crean recursos (create) o se hace referencia a recursos principales recién creados. Por ejemplo, pasar un ID temporal negativo en AdGroupCriterionOperation.remove cuando se llama a AddBatchJobOperations devuelve RequestError.RESOURCE_NAME_MALFORMED.