Mutações

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. Em vez disso, os IDs dos recursos a serem modificados 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 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 na mutação de campanhas, omita o ID do recurso final e adicione :mutate:

https://googleads.googleapis.com/v20/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 uma das seguintes opções: create, update ou remove. Essas são as únicas operações de mutação possíveis.

POST /v20/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. Isso significa que todas são bem-sucedidas juntas ou todo o lote falha se alguma operação falhar. Alguns serviços oferecem suporte a um atributo partialFailure para mudar esse comportamento. Consulte Como fazer mutações em recursos para mais informações 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 /v20/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 é particularmente útil se você já tiver uma representação JSON totalmente formada de um objeto (por exemplo, como retornado por uma chamada de API anterior), mas quiser mudar apenas 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 existente com o resourceName especificado.

POST /v20/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 o status dele no Google Ads como REMOVED. Apenas o resourceName a ser removido é obrigatório.

POST /v20/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"
    }
  ]
}