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 nos 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 usá-lo. Muitos aspectos podem ser ignorados, como tokens de desenvolvedor e autorização, já que são processados pelos scripts do Google Ads, mas é necessário 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, confira este exemplo básico que cria um orçamento da 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. Nesse caso, uma campaignBudgetOperation. Em seguida, especifique create, remove ou e update e updateMask. Os campos específicos em create e update dependem do tipo 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. No exemplo de orçamento da campanha, você pode consultar a documentação de referência da REST para o 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.

Como alternativa, você pode tentar criar uma operação dinamicamente usando o "Teste" para o orçamento da campanha, que permite criar um corpo de solicitação dinamicamente 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 operação, transmitindo uma representação de objeto do recurso que você quer criar.

Consulte o snippet fornecido anteriormente para conferir 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, poderá buscá-lo usando uma Adsapp.search solicitação.

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 que você quer atualizar e especifique uma updateMask que indica 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

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

O valor de retorno é uma matriz de MutateResult objetos, 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. Consulte o guia de práticas recomendadas da API Google Ads para conferir uma explicação completa dos 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 está usando 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 um primeiro argumento e um segundo argumento opcional de opções, incluindo:

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

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