A maioria dos recursos é modificada (criada, atualizada ou removida) usando um método
Mutate
. O método Mutate
é invocado como um HTTP POST
para um URL específico do recurso que corresponde ao padrão do nome do recurso, sem o ID do recurso à direita.
Os IDs dos recursos que serão modificados são enviados no corpo da solicitação
JSON. Isso permite que você envie uma única chamada de API contendo várias operações em
recursos diferentes.
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 modificar campanhas, omita o código de recurso à direita e anexe :mutate
:
https://googleads.googleapis.com/v16/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, por sua vez, pode ser: create
, update
ou remove
. Essas são as únicas operações mutate
possíveis.
POST /v16/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.
Por padrão, as operações em uma única solicitação de API são executadas como um conjunto de ações, o que significa que todas são bem-sucedidas em conjunto ou todo o lote falha se alguma operação falhar. Alguns serviços aceitam um atributo
partialFailure
para mudar esse comportamento. Consulte Como silenciar recursos para ver informações mais 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 completa em JSON do recurso que você pretende criar.
POST /v16/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 executam atualizações esparsas em um recurso atual. 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á tem uma representação JSON totalmente formada de um objeto (por exemplo, conforme retornado por uma chamada de API anterior), mas só quer alterar determinados campos.
Em vez de remover o objeto JSON, você pode simplesmente listar os nomes dos campos a serem
modificados no updateMask
e enviar todo o objeto JSON.
O exemplo abaixo muda name
e status
de uma campanha atual que tem o resourceName
especificado.
POST /v16/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
A remoção de operações exclui um objeto efetivamente, definindo o status do Google Ads como REMOVED
. Apenas o resourceName
a ser removido é necessário.
POST /v16/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" } ] }