Utilizzare ID temporanei

Nomi delle risorse temporanee

BatchJobService supporta i nomi delle risorse temporanee a cui è possibile fare riferimento nelle operazioni successive all'interno dello stesso job batch, anche tra più richieste AddBatchJobOperations sequenziali caricate con un sequence_token. In questo modo, puoi creare una campagna e i relativi gruppi di annunci, annunci e criteri dipendenti in un unico job batch prima che vengano assegnati gli ID lato server. Nelle seguenti regole generali e nell'esempio, una singola richiesta si riferisce a un intero BatchJob in tutti i relativi caricamenti AddBatchJobOperations.

Per fare riferimento a una risorsa appena creata all'interno della stessa richiesta di modifica o dello stesso job batch, specifica un ID intero negativo (ad esempio -1 o -2, escluso 0) nel campo resource_name della nuova risorsa. Ad esempio, quando crei una campagna in una richiesta batch, imposta il nome della risorsa su customers/CUSTOMER_ID/campaigns/-1. Quando crei un gruppo di annunci in un'operazione successiva all'interno della stessa richiesta, fai riferimento a customers/CUSTOMER_ID/campaigns/-1 come campagna principale. L'API sostituisce automaticamente -1 con l'ID campagna effettivo generato al momento della creazione.

Vincoli di utilizzo

Quando utilizzi nomi di risorse temporanei, tieni presente le seguenti regole:

• L'ordine è importante: puoi fare riferimento a un nome di risorsa temporaneo solo dopo averlo definito. In un elenco di operazioni, l'operazione dipendente (ad esempio la creazione di un gruppo di annunci) deve essere visualizzata dopo l'operazione che crea la risorsa principale (ad esempio la creazione di una campagna).
• Ambito di una singola richiesta o di un job batch: i nomi delle risorse temporanee non vengono mantenuti tra job o richieste di modifica separati. Per fare riferimento a una risorsa creata in un job o una richiesta di modifica precedente, utilizza il nome della risorsa generato dal sistema.
• Unicità globale: all'interno di un singolo job o di una singola richiesta di modifica, ogni nome di risorsa temporaneo deve utilizzare un numero intero negativo univoco per tutti i tipi di risorse. Ad esempio, non puoi assegnare -1 sia a una campagna sia a un gruppo di annunci nella stessa richiesta. Il riutilizzo di un ID temporaneo all'interno della stessa richiesta o dello stesso job batch restituisce un errore NewResourceCreationError.DUPLICATE_TEMP_IDS.

Esempio di payload

Supponiamo che tu voglia aggiungere una campagna, un gruppo di annunci e un annuncio in un'unica richiesta API o un unico job batch. Puoi strutturare l'array mutateOperations in un payload della richiesta GoogleAdsService.Mutate o BatchJobService.AddBatchJobOperations, come mostrato nell'esempio JSON REST seguente (con altri campi delle risorse obbligatori omessi per brevità):

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

Questo esempio mostra i seguenti dettagli chiave:

• Il gruppo di annunci utilizza un nuovo ID temporaneo (-2) perché -1 è già assegnato alla campagna.
• Il gruppo di annunci fa riferimento a customers/CUSTOMER_ID/campaigns/-1 per collegarsi alla campagna creata nell'operazione precedente.
• adGroupAdOperation fa riferimento a customers/CUSTOMER_ID/adGroups/-2 e omette resourceName perché nessuna operazione successiva nella richiesta fa riferimento al nuovo annuncio.

Gestione degli errori nei job batch

Poiché le operazioni standard in un job batch vengono eseguite con l'errore parziale attivato (tranne nei sub-batch atomici), se una risorsa principale con un ID temporaneo non supera la convalida, tutte le operazioni secondarie dipendenti che fanno riferimento a quell'ID temporaneo non vanno a buon fine con l'errore NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. Il riutilizzo dello stesso ID negativo in più operazioni create all'interno dello stesso job batch restituisce NewResourceCreationError.DUPLICATE_TEMP_IDS. Gli ID temporanei sono validi solo durante la creazione di risorse (create) o quando si fa riferimento a risorse principali appena create; ad esempio, il passaggio di un ID temporaneo negativo in AdGroupCriterionOperation.remove quando si chiama AddBatchJobOperations restituisce RequestError.RESOURCE_NAME_MALFORMED.