Utilizzare ID temporanei

Nomi delle risorse temporanei

BatchJobService supporta i nomi delle risorse temporanee a cui è possibile fare riferimento nelle operazioni successive all'interno dello stesso job batch, anche in 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 ed esempio, una singola richiesta si riferisce a un intero BatchJob in tutti i suoi caricamenti di 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 i nomi delle 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 separati o richieste di mutazione. Per fare riferimento a una risorsa creata in un job o in una richiesta di modifica precedente, utilizza il nome della risorsa effettivo generato dal sistema.
• Unicità globale:all'interno di un singolo job o di una singola richiesta di modifica, ogni nome di risorsa temporanea deve utilizzare un numero intero negativo univoco in 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 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 una singola richiesta API o in un singolo job batch. Puoi strutturare l'array mutateOperations in un payload di richiesta GoogleAdsService.Mutate o BatchJobService.AddBatchJobOperations come mostrato nel seguente esempio JSON REST (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'opzione errore parziale abilitata (tranne all'interno dei batch secondari atomici), se la convalida di una risorsa principale con un ID temporaneo non va a buon fine, tutte le operazioni secondarie dipendenti che fanno riferimento a quell'ID temporaneo non vanno a buon fine e viene visualizzato 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 quando crei risorse (create) o fai riferimento a risorse principali appena create; ad esempio, il passaggio di un ID temporaneo negativo in AdGroupCriterionOperation.remove quando chiami AddBatchJobOperations restituisce RequestError.RESOURCE_NAME_MALFORMED.