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 acima 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, busque-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"
    }
});

Como 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});