Usar IDs temporários

Nomes de recursos temporários

O BatchJobService é compatível com nomes de recursos temporários que podem ser referenciados em operações subsequentes no mesmo job em lote, inclusive em várias solicitações AddBatchJobOperations sequenciais 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 trabalho em lote, especifique um ID 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 principal. A API substitui automaticamente -1 pelo ID da campanha real gerado na criação.

Restrições de uso

Considere as seguintes regras ao usar nomes de recursos temporários:

• A ordem é importante:só é possível fazer referência a 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 principal (como criar uma campanha).
• Escopo de solicitação única ou job em lote:os nomes de recursos temporários não persistem em jobs separados ou solicitações de mutação. Para fazer referência a um recurso criado em um job ou solicitação de mutação anterior, use o nome de recurso real gerado pelo sistema.
• Unicidade 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 trabalho 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. Você pode 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 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 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 o erro parcial ativado (exceto em sublotes atômicos), se um recurso principal com um ID temporário não passar na validação, todas as operações filhas dependentes que fazem 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ó são válidos ao criar recursos (create) ou referenciar recursos principais recém-criados. Por exemplo, transmitir um ID temporário negativo em AdGroupCriterionOperation.remove ao chamar AddBatchJobOperations retorna RequestError.RESOURCE_NAME_MALFORMED.