Mutações

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"
    }
  ]
}