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 feita 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 para usá-lo. Muitos aspectos podem ser ignorados, como tokens de desenvolvedor e autorização, já que eles são processados para você pelos scripts do Google Ads. No entanto, é necessário formar uma solicitação de mutação válida.

Confira alguns recursos básicos da 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, uma campaignBudgetOperation. Em seguida, especifique create, remove ou ambos update e updateMask. Os campos específicos em create e update dependem do tipo de recurso com que você está trabalhando.

Criar uma operação

Há algumas estratégias que você pode usar para criar uma operação válida. Seguindo o exemplo do orçamento da campanha, você pode consultar a documentação de referência REST para orçamento da campanha e conferir uma lista de todos os campos válidos. Em seguida, preencha os campos adequados ou escreva um código JavaScript personalizado no script para criar um objeto apropriado.

Outra opção é criar uma operação de forma dinâmica usando o recurso "Teste isto" para orçamento da campanha, que permite criar um corpo de solicitação de forma dinâmica escolhendo quais campos 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.

Confira o snippet fornecido anteriormente para um exemplo da operação create.

Remover

Especifique remove na sua 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, recupere-o usando uma solicitação Adsapp.search.

Atualizar

Especifique update na sua 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 os campos que você quer atualizar 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"
    }
});

Processar resultados

Independente do tipo de operação, o valor de retorno é um MutateResult. Use 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, se houver.

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 permitem fazer mutações em várias operações em uma única solicitação com o método AdsApp.mutateAll. É possível criar entidades que dependem umas das outras, como uma hierarquia completa de campanhas em uma única solicitação. Você pode tornar todo o conjunto de operações atômico. Assim, se uma delas falhar, nenhuma será realizada.

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 da API Google Ads. 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 dos scripts do Google Ads usa lowerCamelCase. Os dois casos são aceitos nos scripts do Google Ads. Portanto, 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 V21, se você quiser usar uma versão diferente da padrão dos scripts. Você pode usar qualquer versão disponível publicamente no momento.
  • partialFailure: o padrão desse campo é true. Se definido como true, as operações válidas serão realizadas e as operações com falha vão retornar erros. Se definido como false, e se alguma operação falhar, nenhuma operação será realizada, tornando esse conjunto de operações atômico.

Confira um exemplo com várias operações que cria 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});