Method: customers.googleAds.mutate

Cria, atualiza ou remove recursos. Esse método é compatível com transações atômicas com vários tipos de recursos. Por exemplo, você pode criar atomicamente uma campanha e um orçamento de campanha ou realizar até milhares de mudanças atomicamente.

Esse método é essencialmente um wrapper em torno de uma série de métodos mutate. Os únicos recursos que ele oferece em vez da chamada direta desses métodos são:

  • Transações atômicas
  • Nomes de recursos temporários (descritos abaixo)
  • Latência um pouco reduzida ao fazer uma série de chamadas mutate

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

Benefícios da transação atômica

A atomicidade torna o tratamento de erros muito mais fácil. Se você estiver fazendo uma série de alterações e uma delas falhar, isso pode deixar sua conta em um estado inconsistente. Com a atomicidade, é possível alcançar diretamente o estado escolhido ou a solicitação falha, e você pode tentar novamente.

Nomes de recursos temporários

Nomes de recursos temporários são um tipo especial de nome de recurso usado para criar um recurso e referenciá-lo 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 atomicamente.

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 o pedido de modificação fosse revertido.
  • Os nomes temporários não são lembrados nas 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 recursos sejam diferentes.

Latência

É importante agrupar as modificações por tipo de recurso. Caso contrário, a solicitação pode expirar e falhar. A latência é praticamente igual a uma série de chamadas para métodos mutate individuais, em que cada mudança no tipo de recurso é uma nova chamada. Por exemplo, modificar 10 campanhas e 10 grupos de anúncios equivale a 2 chamadas. Já a modificação de 1 campanha, 1 grupo de anúncios, 1 campanha e 1 grupo de anúncios equivale a 4 chamadas.

AdCustomizerErrorAdErrorAdGroupAdErrorAdGroupCriterionErrorAdGroupErrorAssetErrorAuthenticationErrorAuthorizationErrorBiddingErrorCampaignBudgetErrorCampaignCriterionErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

Solicitação HTTP

POST https://googleads.googleapis.com/v15/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. Lista de operações a serem realizadas em recursos individuais.
partialFailure

boolean

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

boolean

Se verdadeiro, a solicitação é 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 deve ser retornado após a mutação. O recurso mutável só vai ser retornado se tiver o campo de resposta apropriado. 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 somente quando partialFailure = true e todos os erros ocorrem dentro das operações. Se ocorrer algum erro fora das operações (por exemplo, erros de autenticação), vamos retornar um erro no nível da RPC.
mutateOperationResponses[]

object (MutateOperationResponse)

Todas as respostas para a função mutate.

Escopos de autorização

Requer o seguinte escopo OAuth:

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

Para mais informações, consulte a Visão geral do OAuth 2.0.