Method: customers.googleAds.mutate

Cria, atualiza ou remove recursos. Esse método oferece suporte a transações atômicas com vários tipos de recursos. Por exemplo, é possível criar uma campanha e um orçamento de campanha ou realizar até milhares de mutações de forma atômica.

Esse método é basicamente um wrapper para uma série de métodos de mutação. Os únicos recursos que ele oferece em relação à chamada direta desses métodos são:

  • Transações atômicas
  • Nomes de recursos temporários (descritos abaixo)
  • A latência foi reduzida ao fazer uma série de chamadas de mutação.

Observação: apenas os recursos compatíveis com transações atômicas são incluídos. Portanto, esse método não pode substituir todas as chamadas para serviços individuais.

Benefícios das transações atômicas

A atomicidade facilita muito o tratamento de erros. Se você estiver fazendo uma série de mudanças e uma delas falhar, sua conta poderá ficar em um estado inconsistente. Com a atomicidade, você alcança o estado escolhido diretamente ou a solicitação falha e você pode tentar novamente.

Nomes de recursos temporários

Os nomes de recursos temporários são um tipo especial de nome de recurso usado para criar um recurso e fazer referência a ele na mesma solicitação. Por exemplo, se um orçamento de campanha for criado com resourceName igual a customers/123/campaignBudgets/-1, esse nome de recurso poderá ser reutilizado no campo Campaign.budget na mesma solicitação. Dessa forma, os dois recursos são criados e vinculados de forma atômica.

Para criar um nome de recurso temporário, coloque um número negativo na parte do nome que o servidor normalmente alocaria.

Observação:

  • Os recursos precisam ser criados com um nome temporário antes que o nome possa ser reutilizado. Por exemplo, o exemplo anterior de CampaignBudget+Campaign falharia se a ordem de mutação fosse revertida.
  • Os nomes temporários não são lembrados em todas as solicitações.
  • Não há limite para o número de nomes temporários em uma solicitação.
  • Cada nome temporário precisa usar um número negativo exclusivo, mesmo que os tipos de recurso sejam diferentes.

Latência

É importante agrupar as mutações por tipo de recurso, caso contrário, o tempo limite da solicitação pode expirar e ela falhar. A latência é aproximadamente igual a uma série de chamadas para métodos de mutação individuais, em que cada mudança no tipo de recurso é uma nova chamada. Por exemplo, a mutação de 10 campanhas e 10 grupos de anúncios é como 2 chamadas, enquanto a mutação de 1 campanha, 1 grupo de anúncios, 1 campanha e 1 grupo de anúncios é como 4 chamadas.

Lista de erros gerados: AdCustomizerError AdError AdGroupAdError AdGroupCriterionError AdGroupError AssetError AuthenticationError AuthorizationError BiddingError CampaignBudgetError CampaignCriterionError CampaignError CampaignExperimentError CampaignSharedSetError CollectionSizeError ContextError ConversionActionError CriterionError CustomerFeedError DatabaseError DateError DateRangeError DistinctError ExtensionFeedItemError ExtensionSettingError FeedAttributeReferenceError FeedError FeedItemError FeedItemSetError FieldError FieldMaskError FunctionParsingError HeaderError ImageError InternalError KeywordPlanAdGroupKeywordError KeywordPlanCampaignError KeywordPlanError LabelError ListOperationError MediaUploadError MutateError NewResourceCreationError NullError OperationAccessDeniedError PolicyFindingError PolicyViolationError QuotaError RangeError RequestError ResourceCountLimitExceededError SettingError SharedSetError SizeLimitError StringFormatError StringLengthError UrlFieldError UserListError YoutubeVideoRegistrationError

Solicitação HTTP

POST https://googleads.googleapis.com/v19/customers/{customerId}/googleAds:mutate

O URL usa a sintaxe de transcodificação gRPC.

Parâmetros de caminho

Parâmetros
customerId

string

Obrigatório. O ID do cliente cujos recursos estão sendo modificados.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON 
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
Campos
mutateOperations[]

object (MutateOperation)

Obrigatório. A lista de operações a serem realizadas em recursos individuais.
partialFailure

boolean

Se for "true", as operações bem-sucedidas serão realizadas e as operações inválidas vão retornar erros. Se for falso, todas as operações serão realizadas em uma transação somente se forem válidas. O padrão é false
validateOnly

boolean

Se for verdadeiro, a solicitação será validada, mas não executada. Somente erros são retornados, não resultados.
responseContentType

enum (ResponseContentType)

A configuração do tipo de conteúdo da resposta. Determina se o recurso mutável ou apenas o nome do recurso precisa ser retornado após a mutação. O recurso mutável só será retornado se tiver o campo de resposta adequado. Por exemplo, MutateCampaignResult.campaign.

Corpo da resposta

Mensagem de resposta para GoogleAdsService.Mutate.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON 
{
  "partialFailureError": {
    object (Status)
  },
  "mutateOperationResponses": [
    {
      object (MutateOperationResponse)
    }
  ]
}
Campos
partialFailureError

object (Status)

Erros relacionados a falhas de operação no modo de falha parcial. Retornado apenas quando partialFailure = true e todos os erros ocorrem dentro das operações. Se ocorrerem erros fora das operações (por exemplo, erros de autenticação), retornaremos um erro no nível do RPC.
mutateOperationResponses[]

object (MutateOperationResponse)

Todas as respostas para a mutação.

Escopos de autorização

Requer o seguinte escopo OAuth:

  • https://www.googleapis.com/auth/adwords

Para mais informações, consulte OAuth 2.0 Overview.