Alterar

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 no GoogleAdsService.mutate também podem ser feitas nos scripts do Google Ads, incluindo a criação e o gerenciamento de campanhas.

Como esse recurso permite o acesso a uma parte tão grande 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 é preciso formar uma solicitação de mutação válida.

Confira alguns recursos básicos sobre a 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 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, neste caso, um campaignBudgetOperation. Em seguida, especifique create, remove ou ambos 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

Existem algumas estratégias que você pode usar para criar uma operação válida. Ainda no exemplo do orçamento da campanha, você pode consultar a documentação de referência da REST para o orçamento da 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 seu script para criar um objeto adequado.

Como alternativa, você pode tentar criar uma operação dinamicamente usando o recurso "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 ver 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, busque-o 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 os campos que você quer atualizar e especifique um updateMask que indique exatamente quais campos você planeja mudar nessa 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

Seja qual for o 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 de 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 modificar 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 de campanha completa em uma única solicitação. Se quiser, você pode tornar todo o conjunto de operações atômico. Assim, se uma 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. Portanto, consulte o guia de práticas recomendadas da API Google Ads para uma explicação completa sobre os 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. Ambos os 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 V26, 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: o valor padrão desse 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 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});