Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.

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 do nome do recurso, sem o ID de recurso final. Os IDs dos recursos a serem transformados são enviados no corpo da solicitação JSON. Com isso, você pode enviar uma única chamada de API que contém várias operações em diferentes recursos.

Por exemplo, o nome de um recurso de campanha tem o seguinte formato:

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

Para derivar o URL usado para modificar campanhas, omita o ID do recurso final e anexe :mutate:

https://googleads.googleapis.com/v11/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 mutáveis possíveis.

POST /v11/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 é compatível com milhares de operações em uma única chamada de API. O guia Limites de 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 serão bem-sucedidas juntas ou que o lote inteiro falhará se qualquer uma das operações falhar. Alguns serviços são compatíveis com um atributo partialFailure para mudar esse comportamento. Consulte Como modificar recursos para informações mais detalhadas sobre a semântica de operação mutaçã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 /v11/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

Essas operações 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á tiver uma representação JSON totalmente formada de um objeto (por exemplo, como retornado por uma chamada de API anterior), mas quiser alterar apenas determinados campos. Em vez de remover o objeto JSON, basta listar os nomes dos campos a serem modificados no updateMask e enviar todo o objeto JSON.

O exemplo abaixo altera name e status de uma campanha existente que tem o resourceName fornecido.

POST /v11/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 efetivamente, definindo o status do Google Ads como REMOVED. Somente o resourceName a ser removido é obrigatório.

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