A maioria dos recursos é modificada (criada, atualizada ou removida) usando um método
Mutate. O método Mutate é invocado como um POST HTTP para um URL específico do recurso
que corresponde ao padrão de nome do recurso, sem o ID do recurso final.
Os IDs dos recursos a serem mutados são enviados no corpo da solicitação JSON. Isso permite enviar uma única chamada de API que contém várias operações em
diferentes recursos.
Por exemplo, o nome do recurso de uma campanha usa o seguinte formato:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Para derivar o URL usado para campanhas de mutação, omita o ID do recurso final e
adicione :mutate:
https://googleads.googleapis.com/v19/customers/CUSTOMER_ID/campaigns:mutate
Uma mensagem Mutate contém um objeto JSON de nível superior com uma matriz operations
que pode conter muitos objetos operation. Cada operação pode ser uma
das seguintes: create, update ou remove. Estas são as únicas operações de mutação
possíveis.
POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ ... ] }
A maioria dos serviços oferece suporte a milhares de operações em uma única chamada de API. O guia Limites do sistema documenta as limitações nos tamanhos de solicitação.
As operações em uma única solicitação de API são executadas como um conjunto de ações por
padrão, o que significa que todas elas são bem-sucedidas juntas ou todo o lote falha se
uma única operação falhar. Alguns serviços oferecem suporte a um atributo
partialFailure
para mudar esse comportamento. Consulte Recursos de mutação
para mais informações detalhadas sobre a semântica da operação de mutação.
Criar
As operações de criação produzem novas entidades e precisam incluir uma representação JSON completa do recurso que você quer criar.
POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "create": { "name": "An example campaign", "status": "PAUSED", "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/CAMPAIGN_BUDGET_ID", "advertisingChannelType": "SEARCH", "networkSettings": { "targetGoogleSearch": true, "targetSearchNetwork": true, "targetContentNetwork": true, "targetPartnerSearchNetwork": false }, "target_spend": {} } } ] }
Atualizar
As operações de atualização realizam atualizações esparsas em um recurso existente. Basta especificar os campos que você quer modificar.
Para especificar os campos que você quer atualizar, defina o atributo updateMask como
uma lista separada por vírgulas de nomes de campos. Isso é útil principalmente se você
já tiver uma representação JSON totalmente formada de um objeto (por exemplo, retornado por uma chamada de API anterior), mas quiser mudar apenas alguns campos.
Em vez de podar o objeto JSON, basta listar os nomes de campo a serem
modificados no updateMask e enviar o objeto JSON inteiro.
O exemplo abaixo muda o name e o status de uma campanha existente com
o resourceName fornecido.
POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "updateMask": "name,status", "update": { "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID", "name": "My renamed campaign", "status": "PAUSED", } } ] }
Remover
As operações de remoção excluem efetivamente um objeto, definindo o status dele no Google Ads como REMOVED. Apenas o resourceName a ser removido é necessário.
POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID" } ] }