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, é possível 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 oferecidos 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: apenas os recursos que suportam 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 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, é possível que sua conta fique 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

Nomes de recursos temporários são um tipo especial de nome de recurso usado para criar um recurso e fazer referência a esse recurso 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 devem ser criados com um nome temporário antes que o nome possa ser reutilizado. Por exemplo, o exemplo anterior CampaignBudget+Campaign falharia se o pedido de modificação fosse invertido.
  • 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 se os tipos de recursos forem diferentes.

Latência

É importante agrupar as mudanças feitas por tipo de recurso. Caso contrário, a solicitação pode expirar e falhar. A latência é aproximadamente 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, mudar 10 campanhas e depois 10 grupos de anúncios equivale a 2 chamadas. Já as modificações de 1 campanha, 1 grupo de anúncios, 1 campanha e 1 grupo de anúncios equivalem a 4 chamadas.

lista de erros gerados {3LatLngErrorRange}{4ErrorSettings}{4ErrorSettings}{3ErrorPolicy{/4ErrorSettings}{4ErrorPolicy{/ErrorRangeError{4ErrorPolicy{/1ErrorLimit{/38ErrorLimit{/3CampaignErrorLimit{/4ErrorValueError{/38ErrorLimit{/4Error).{/3ErrorPolicy{/3ErrorError{35ErrorError"){/313Error AuthorizationErrorBiddingErrorCampaignBudgetErrorCampaignCriterionErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

Solicitação HTTP

POST https://googleads.googleapis.com/v16/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 executadas em recursos individuais.
partialFailure

boolean

Se verdadeiro, as operações bem-sucedidas serão executadas 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 de 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 apenas 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), retornaremos um erro de nível 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.