Usar IDs temporários

Nomes de recursos temporários

BatchJobService aceita nomes de recursos temporários que podem ser referenciados em operações subsequentes no mesmo job em lote, incluindo várias solicitações sequenciais AddBatchJobOperations enviadas com um sequence_token. Isso permite criar uma campanha e os grupos de anúncios, anúncios e critérios dependentes 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, excluindo 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, faça referência a customers/CUSTOMER_ID/campaigns/-1 como a campanha mãe. A API substitui automaticamente -1 pelo ID da campanha real gerado após a criação.

Restrições de uso

Considere as 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 a criação de um grupo de anúncios) precisa aparecer após a operação que cria o recurso pai (como a criação de 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 referenciar um recurso criado em um job ou 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. A reutilização de 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 JSON REST a seguir (com outros campos de recursos obrigatórios omitidos para maior clareza):

{
  "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 principais:

• 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 falha parcial ativada (exceto em sub-lotes atômicos), se um recurso pai com um ID temporário falhar na validação, todas as operações filhas dependentes que fazem referência a esse ID temporário falharão com NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. A reutilização do mesmo ID negativo em várias operações create no mesmo job em lote retorna NewResourceCreationError.DUPLICATE_TEMP_IDS. Os IDs temporários só são válidos ao criar recursos (create) ou referenciar recursos pais recém- criados. Por exemplo, transmitir um ID temporário negativo em AdGroupCriterionOperation.remove ao chamar AddBatchJobOperations retorna RequestError.RESOURCE_NAME_MALFORMED.