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, incluse 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 relativo nome 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 temporanee, tieni presente le seguenti regole:

• L'ordine è importante: puoi fare riferimento a un nome di risorsa temporanea 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 relativa risorsa principale (ad esempio la creazione di una campagna).
• Ambito di una singola richiesta o di un singolo job batch: i nomi delle risorse temporanee non vengono mantenuti tra job o richieste di mutazione separati. Per fare riferimento a una risorsa creata in un job o in una richiesta di modifica precedente, utilizza il relativo nome 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 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 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 una singola richiesta API o in un singolo job batch. Puoi strutturare l'array mutateOperations in un payload della richiesta GoogleAdsService.Mutate o BatchJobService.AddBatchJobOperations come mostrato nel seguente esempio JSON REST (con altri campi risorsa 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 illustra 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 errore parziale abilitato (tranne che all'interno di batch secondari 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 riescono con 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.