Mutações

Os scripts do Google Ads oferecem suporte a mutações genéricas disponíveis na API Google Ads. A maioria das operações que podem ser realizadas em GoogleAdsService.mutate também pode ser realizada em scripts do Google Ads, incluindo a criação e o gerenciamento de campanhas.

Como esse recurso permite o acesso a uma grande parte da API Google Ads, é importante ter um entendimento básico das convenções da API Google Ads para usar esse recurso. Muitos aspectos podem ser pulados, como tokens de desenvolvedor e autorização, porque são tratados pelos scripts do Google Ads, mas você precisa formar uma solicitação de mutação válida.

Confira alguns recursos básicos na interface REST da API Google Ads que você precisa conhecer antes de continuar com este guia:

Exemplo básico

Para demonstrar a funcionalidade, considere este exemplo básico que cria um orçamento de campanha:

const budgetResult = AdsApp.mutate({
    campaignBudgetOperation: {
      create: {
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });

Uma chamada para AdsApp.mutate usa um objeto JSON que representa um único MutateOperation. Nesse objeto, você especifica o tipo de operação que está realizando, neste caso, um campaignBudgetOperation. Em seguida, especifique create, remove ou update e updateMask. Os campos específicos em create e update dependem do tipo específico de recurso em que você está operando.

Criar uma operação

Há algumas estratégias que você pode usar para criar uma operação válida. Usando o exemplo de orçamento de campanha, você pode consultar a documentação de referência REST para o orçamento de campanha para ver uma lista de todos os campos válidos e, em seguida, preencher os campos apropriados ou escrever um código JavaScript personalizado no script para criar um objeto adequado.

Se preferir, crie uma operação dinamicamente usando o recurso "Faça um teste" para o orçamento da campanha. Com ele, é possível criar um corpo de solicitação de maneira dinâmica, escolhendo os campos que você quer adicionar. Em seguida, extraia o conteúdo da operação do resultado gerado e adicione-o à chamada mutate depois de especificar o tipo de operação.

Tipos de operação

Criar

Especifique create na sua operação, transmitindo uma representação de objeto do recurso que você quer criar.

Veja acima um exemplo da operação create.

Remover

Especifique remove na operação, transmitindo o nome do recurso que você quer remover, por exemplo:

AdsApp.mutate({
    adGroupOperation: {
        remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
    }
});

Se você não souber o nome do recurso de uma entidade, é possível fazer a busca usando uma solicitação Adsapp.search.

Atualizar

Especifique update na operação, transmitindo um objeto com o nome do recurso especificado para que o sistema possa determinar qual objeto você quer atualizar. Além disso, preencha todos os campos para atualizar os valores e especifique um updateMask que indique exatamente quais campos você planeja mudar nesta solicitação. Não inclua o nome do recurso na máscara de atualização.

Exemplo de uma operação update:

const campaignResult = AdsApp.mutate({
    campaignOperation: {
        update: {
            resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
            status: "PAUSED",
            name: "[Paused] My campaign"
        },
        updateMask: "name,status"
    }
});

Como processar resultados

Independentemente do tipo de operação, o valor de retorno é um MutateResult. É possível usar o nome do recurso retornado para consultar o estado atual do recurso após a mutação e verificar se a operação foi bem-sucedida ou quais erros ocorreram.

Confira um exemplo que mostra um fluxo básico para verificar um resultado e imprimir algumas informações nos registros:

const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
    console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
    console.log("Errors encountered:");
    for (const error of result.getErrorMessages()) {
        console.log(error);
    }
}

Várias operações

Os scripts do Google Ads também oferecem suporte à modificação de várias operações em uma única solicitação com o método AdsApp.mutateAll. É possível criar entidades dependentes umas das outras, como uma hierarquia de campanha completa em uma única solicitação. Você pode tornar todo o conjunto de operações atômico, para que, se uma falhar, nenhuma seja executada.

O valor de retorno é uma matriz de objetos MutateResult, um para cada operação fornecida e na mesma ordem das operações iniciais.

Esse recurso funciona da mesma forma que o recurso da API Google Ads. Portanto, consulte o guia de práticas recomendadas da API Google Ads para uma explicação completa sobre IDs temporários e outras considerações. O guia usa snake_case para representar nomes de campos, enquanto a documentação de scripts do Google Ads usa lowerCamelCase. Ambos os casos são aceitos nos scripts do Google Ads. Assim, você pode copiar o código diretamente desse guia.

Para fazer várias operações em uma única solicitação, colete todas as operações em uma matriz e chame AdsApp.mutateAll. A chamada mutateAll usa a matriz de operações como primeiro argumento e um segundo argumento opcional de opções, incluindo:

  • apiVersion: é possível especificar uma versão personalizada da API, como V18, se você quiser usar uma versão diferente do padrão dos scripts. Você pode usar qualquer versão disponível publicamente no momento.
  • partialFailure: esse campo tem como padrão true. Se definido como true, as operações válidas são realizadas e as operações com falha retornam erros. Se definido como false, se qualquer operação falhar, nenhuma operação será realizada, tornando esse conjunto de operações atômico.

Veja um exemplo com várias operações que criam um orçamento de campanha, uma campanha e um grupo de anúncios em uma solicitação atômica.

const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
    campaignBudgetOperation: {
      create: {
        resourceName: budgetId,
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });
operations.push({
    campaignOperation: {
      create: {
        resourceName: campaignId,
        name: 'New Campaign ' + new Date(),
        advertisingChannelType: 'SEARCH',
        manualCpc: {},
        campaignBudget: budgetId,
        advertisingChannelType: 'DISPLAY',
        networkSettings: {
          targetContentNetwork: true
        }
      }
    }
  });
operations.push({
    adGroupOperation: {
      create: {
        campaign: campaignId,
        name: 'New AdGroup ' + new Date(),
        optimizedTargetingEnabled: true
      }
    }
  });
const results = AdsApp.mutateAll(
    operations, {partialFailure: false});