Ads Manager Scripts

A classe AdsManagerApp nos scripts do Google Ads permite gerenciar contas vinculadas à sua conta de administrador. É possível gerenciar todas as suas contas de anunciante com um único script em vez de criar um script separado para cada conta.

Recuperar lista de contas

Você pode recuperar contas de uma conta de administrador usando o método accounts, por exemplo:

const accountSelector = AdsManagerApp.accounts()
    .withCondition('customer_client.descriptive_name = "My Account"');

const accountIterator = accountSelector.get();

Há algumas restrições para as contas que podem ser recuperadas:

• Não será possível recuperar as contas de administrador se você tiver uma hierarquia de vários níveis. Somente as contas de cliente podem ser selecionadas.
• Por padrão, contas encerradas, canceladas e suspensas não são retornadas. Para substituir esse comportamento, chame withCondition especificando um filtro diferente para customer_client.status.

A chamada accounts recupera a lista de todas as contas de cliente na hierarquia de contas de administrador por padrão. É possível usar o método withLimit da classe ManagedAccountSelector para restringir o número de contas recuperadas pelo script. Outra opção é selecionar as contas pelos IDs de cliente usando o método withIds:

// Hyphens in the account ID are optional.
const accountSelector = AdsManagerApp.accounts()
    .withIds(['123-456-7890', '234-567-8901', '345-678-9012']);

Trabalhar em contas de clientes

Depois de recuperar as contas de cliente, será possível interagir com elas usando os métodos hasNext e next do iterador. É necessário usar o método select para alternar o contexto de execução para uma conta de cliente. Depois de selecionar uma conta de cliente, todas as outras chamadas de API se aplicam a ela até que você selecione outra conta explicitamente:

// Keep track of the manager account for future reference.
const managerAccount = AdsApp.currentAccount();

// Select your accounts
const accountIterator = AdsManagerApp.accounts()
// ... Write some logic here to select the accounts you want using
// withCondition or withIds

// Iterate through the list of accounts
for (const account of accountIterator) {
  // Select the client account.
  AdsManagerApp.select(account);

  // Select campaigns under the client account
  const campaignIterator = AdsApp.campaigns().get();

  // Operate on client account
  ...
}

Trabalhar em contas em paralelo

Com os scripts do Google Ads, é possível operar em várias contas de cliente simultaneamente usando o método executeInParallel da classe ManagedAccountSelector. O método executeInParallel tem a seguinte assinatura:

function executeInParallel(functionName, optionalCallbackFunctionName, optionalInput);

O método executeInParallel executa uma função especificada por functionName em cada ManagedAccount correspondente ao ManagedAccountSelector. Depois que todas as contas forem processadas, a função de callback, se especificada por optionalCallbackFunctionName, será executada uma vez, transmitindo uma lista de objetos ExecutionResult como argumento para qualquer processamento adicional. O uso típico é mostrado abaixo:

function main() {
  const accountSelector = AdsManagerApp.accounts()
      .withLimit(50)
      .withCondition('customer_client.currency_code = "USD"');

  accountSelector.executeInParallel("processClientAccount", "afterProcessAllClientAccounts");
}

function processClientAccount() {
  const clientAccount = AdsApp.currentAccount();

  // Process your client account here.
  ...

  // optionally, return a result, as text.
  return "";
}

function afterProcessAllClientAccounts(results) {
  for (const result of results) {
    // Process the result further
    ...
  }
}

A função especificada por functionName pode aceitar um argumento de string (optionalInput). Esse parâmetro pode ser usado para transmitir outro parâmetro a todos os métodos paralelos chamados por executeInParallel:

function main() {
  const accountSelector = AdsManagerApp.accounts().withIds([1234567890, 3456787890]);
  const sharedParameter = "INSERT_SHARED_PARAMETER_HERE";
  accountSelector.executeInParallel("processClientAccount", null, sharedParameter);
}

function processClientAccount(sharedParameter) {
  // Process your client account here.
  ...
}

Para transmitir um objeto de configuração JavaScript que contenha configurações específicas da conta, primeiro converta-o em uma string usando o método JSON.stringify:

function main() {
  ...
  const accountFlags = {
    '1234567890': {
       'label': 'Brand 1 campaigns',
     },
    '3456787890': {
       'label': 'Brand 2 campaigns',
     }
  };
  accountSelector.executeInParallel("processClientAccount", null,
      JSON.stringify(accountFlags));
  ...
}

function processClientAccount(sharedParameter) {
  const accountFlags = JSON.parse(sharedParameter);
  // Process your client account here.
  ...
}

A função especificada por functionName também pode retornar uma string em vez de um objeto usando JSON.stringify:

function processClientAccount() {
  ...
  const jsonObj = {value: 10, list: [1,2,3,4,5,6], name: "Joe Smith"};
  return JSON.stringify(jsonObj);
}

Os valores retornados são transmitidos para a função de callback em uma lista de objetos ExecutionResult. Se você retornou uma string JSON da função, poderá convertê-la de volta em um objeto JavaScript usando o método JSON.parse:

function callbackFunctionName(results) {
  for (var i = 0; i < results.length; i++) {
    var resultObj = JSON.parse(results[i].getReturnValue());
  }
}

O método executeInParallel opera no máximo 50 accounts, portanto, será necessário implementar suas próprias restrições para limitar o número de contas recuperadas pelo script. Você pode usar o método withLimit ou withIds da classe ManagedAccountSelector para restringir o número de contas que seu script recupera.

Limites de tempo de execução

Consulte esta página para detalhes sobre os limites de tempo de execução dos scripts do Gerenciador de anúncios.