Mutações

A maioria dos recursos é modificada (criada, atualizada ou removida) usando um Mutate. . O método Mutate é invocado como HTTP POST para uma solicitação URL que corresponde ao padrão de nome de recurso, sem o ID do recurso à direita. Os IDs dos recursos que serão transformados são enviados na solicitação JSON corpo Isso permite que você envie uma única chamada de API que contém várias operações 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 ID do recurso à direita e anexar :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 uma de: create, update ou remove. Essas são as únicas variáveis de mutate as operações.

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 sistema limite documenta as limitações nos tamanhos das solicitações.

As operações em uma única solicitação de API são executadas como um conjunto de ações, padrão, o que significa que todos serão bem-sucedidos juntos ou o lote inteiro falhará se qualquer operação falha. Alguns serviços dão suporte a uma Atributo partialFailure para mudar esse comportamento. Consulte Como mudar recursos. para obter informações mais detalhadas sobre a semântica da operação mutate.

Criar

As operações de criação produzem novas entidades e precisam incluir um JSON completo representação 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. Você só precisa para 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 é especialmente útil se você já têm uma representação JSON completa de um objeto (por exemplo, como retornados por uma chamada de API anterior), mas só querem alterar determinados campos. Em vez de remover o objeto JSON, basta listar os nomes dos campos a serem modificado no updateMask e enviar todo o objeto JSON.

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

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