Mutações

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

Como esse recurso permite acesso a uma grande parte da API Google Ads, é importante ter um entendimento básico das convenções da Google Ads API para usá-lo. Muitos aspectos podem ser ignorados, como tokens de desenvolvedor e autorização, já que eles são gerenciados pelos scripts do Google Ads, mas é necessário formar uma solicitação de modificação válida.

Veja alguns recursos básicos da interface REST da Google Ads API que você deve conhecer antes de prosseguir 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á executando. 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

Algumas estratégias podem ser usadas para criar uma operação válida. Ainda no exemplo de orçamento de campanha, consulte a documentação de referência da REST para orçamento de campanha e veja uma lista de todos os campos válidos. Em seguida, preencha os campos apropriados ou escreva um código JavaScript personalizado no seu script para criar um objeto apropriado.

Como alternativa, você pode tentar criar uma operação de forma dinâmica usando o recurso"Faça um teste" para o orçamento da campanha, que permite criar um corpo de solicitação de forma dinâmica escolhendo os campos que você quer adicionar. Depois, é possível extrair o conteúdo da operação do resultado gerado e adicioná-lo à 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 não souber o nome do recurso de uma entidade, busque-a 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 em que você quer atualizar os valores e especifique um updateMask que indique exatamente quais campos você planeja alterar na 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

Seja qual for o tipo de operação, o valor de retorno é uma MutateResult. Use o nome do recurso retornado para consultar o estado atual dele após a função mutate e verificar se a operação foi bem-sucedida ou quais erros ocorreram, se houver.

Veja um exemplo que mostra um fluxo básico para verificar um resultado e exibir 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 são compatíveis com a modificação de várias operações em uma única solicitação com o método AdsApp.mutateAll. É possível tornar entidades dependentes umas das outras, como uma hierarquia de campanha completa em uma única solicitação. Opcionalmente, você pode tornar todo o conjunto de operações atômico. Portanto, se alguma falhar, nenhuma será 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 campo, enquanto a documentação de scripts do Google Ads está usando lowerCamelCase. Os dois casos são aceitos nos scripts do Google Ads, então 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: você poderá especificar uma versão personalizada da API, como V16, se quiser usar uma versão diferente da padrão dos scripts. É possível usar qualquer versão disponível publicamente no momento.
  • partialFailure: o padrão deste campo é true. Se definido como true, as operações válidas serão executadas e as operações com falha retornarão erros. Se definido como false, se alguma 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});