A maioria dos recursos é modificada (criada, atualizada ou removida) usando um método
Mutate. O método Mutate é invocado como HTTP POST para um URL específico do recurso
que corresponde ao padrão de nome do recurso, sem o ID do recurso à direita.
Os IDs dos recursos que serão transformados são enviados no corpo da solicitação JSON. Assim, é possível 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 modificar campanhas, omita o código do recurso à direita e anexe :mutate:
https://googleads.googleapis.com/v17/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: create, update ou remove. Essas são as únicas operações mutate possíveis.
POST /v17/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 das solicitações.
As operações em uma única solicitação de API são executadas, por padrão, como um conjunto de ações. Isso significa que todas serão bem-sucedidas juntas ou o lote inteiro falhará se uma única operação falhar. Alguns serviços oferecem suporte a um
atributo partialFailure
para mudar esse comportamento. Consulte Como alterar recursos para informações mais detalhadas sobre a semântica da operação de modificação.
Criar
As operações de criação produzem novas entidades e precisam incluir uma representação JSON completa do recurso que você pretende criar.
POST /v17/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 é particularmente útil se você já tem uma representação JSON totalmente formada de um objeto (por exemplo, como retornado por uma chamada de API anterior), mas quer apenas alterar determinados campos.
Em vez de remover o objeto JSON, basta listar os nomes dos campos a serem
modificados no updateMask e enviar o objeto JSON inteiro.
O exemplo abaixo muda o name e o status de uma campanha atual com o resourceName especificado.
POST /v17/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 um objeto, definindo seu status no Google Ads como REMOVED. É necessário apenas o resourceName a ser removido.
POST /v17/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"
}
]
}