Usar IDs temporários

Nomes de recursos temporários

O BatchJobService aceita nomes de recursos temporários que podem ser referenciados em operações subsequentes no mesmo job em lote, incluindo em várias solicitações AddBatchJobOperations sequenciais enviadas com um sequence_token. Isso permite que você crie uma campanha e os grupos de anúncios, anúncios e critérios dependentes dela em um único job em lote antes que os IDs do lado do servidor sejam atribuídos. Nas regras gerais e no exemplo a seguir, uma única solicitação se refere a um BatchJob inteiro em todos os uploads de AddBatchJobOperations.

Para referenciar um recurso recém-criado na mesma solicitação de mutação ou job em lote, especifique um ID de número inteiro negativo (como -1 ou -2, exceto 0) no campo resource_name do novo recurso. Por exemplo, ao criar uma campanha em uma solicitação em lote, defina o nome do recurso como customers/CUSTOMER_ID/campaigns/-1. Ao criar um grupo de anúncios em uma operação posterior na mesma solicitação, use customers/CUSTOMER_ID/campaigns/-1 como a campanha principal. A API substitui automaticamente -1 pelo ID da campanha gerado na criação.

Restrições de uso

Lembre-se das seguintes regras ao usar nomes de recursos temporários:

• A ordem é importante: só é possível referenciar um nome de recurso temporário depois de defini-lo. Em uma lista de operações, a operação dependente (como criar um grupo de anúncios) precisa aparecer depois da operação que cria o recurso pai (como criar uma campanha).
• Escopo de solicitação única ou job em lote: os nomes de recursos temporários não persistem em jobs ou solicitações de mutação separados. Para fazer referência a um recurso criado em um job ou uma solicitação de mutação anterior, use o nome de recurso real gerado pelo sistema.
• Exclusividade global: em um único job ou solicitação de mutação, cada nome de recurso temporário precisa usar um número inteiro negativo exclusivo em todos os tipos de recursos. Por exemplo, não é possível atribuir -1 a uma campanha e a um grupo de anúncios na mesma solicitação. Reutilizar um ID temporário na mesma solicitação ou job em lote retorna um erro NewResourceCreationError.DUPLICATE_TEMP_IDS.

Exemplo de payload

Suponha que você queira adicionar uma campanha, um grupo de anúncios e um anúncio em uma única solicitação de API ou job em lote. É possível estruturar a matriz mutateOperations em um payload de solicitação GoogleAdsService.Mutate ou BatchJobService.AddBatchJobOperations, conforme mostrado no exemplo de JSON REST a seguir (com outros campos de recursos obrigatórios omitidos para fins de brevidade):

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

Este exemplo demonstra os seguintes detalhes importantes:

• O grupo de anúncios usa um novo ID temporário (-2) porque -1 já está atribuído à campanha.
• O grupo de anúncios faz referência a customers/CUSTOMER_ID/campaigns/-1 para se vincular à campanha criada na operação anterior.
• O adGroupAdOperation faz referência a customers/CUSTOMER_ID/adGroups/-2 e omite resourceName porque nenhuma operação subsequente na solicitação faz referência ao novo anúncio.

Tratamento de erros em jobs em lote

Como as operações padrão em um job em lote são executadas com a falha parcial ativada (exceto em sublotes atômicos), se um recurso pai com um ID temporário falhar na validação, todas as operações filhas dependentes que fizerem referência a esse ID temporário vão falhar com NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. Reutilizar o mesmo ID negativo em várias operações create no mesmo job em lote retorna NewResourceCreationError.DUPLICATE_TEMP_IDS. Os IDs temporários são válidos apenas ao criar recursos (create) ou referenciar recursos pai recém-criados. Por exemplo, transmitir um ID temporário negativo em AdGroupCriterionOperation.remove ao chamar AddBatchJobOperations retorna RequestError.RESOURCE_NAME_MALFORMED.