Ads Manager Scripts

A classe AdsManagerApp nos scripts do Google Ads permite gerenciar contas vinculadas à sua conta de administrador. Você pode gerenciar todas as contas de anunciantes com um único script, em vez de criar um script separado para cada conta.

Recuperar a lista de contas

É possível recuperar contas em uma conta de administrador usando o accounts método. 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:

• As contas de administrador não podem ser recuperadas se você tiver uma hierarquia multinível. Somente as contas de cliente podem ser selecionadas.
• Por padrão, as contas fechadas, canceladas e suspensas não são retornadas. Você pode substituir esse comportamento chamando withCondition e especificando um filtro diferente para customer_client.status.

A chamada accounts recupera a lista de todas as contas de cliente na hierarquia da conta de administrador por padrão. Você pode usar o withLimit método da ManagedAccountSelector classe para restringir o número de contas que o script recupera. Outra opção é selecionar as contas pelos IDs de cliente usando o withIds método:

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

Trabalhar com contas de cliente

Depois de recuperar as contas de cliente, você pode iterar por elas usando os métodos hasNext e next do iterador. É necessário usar o select método para mudar o contexto de execução para uma conta de cliente. Depois de selecionar uma conta de cliente, todas as outras chamadas de API serão aplicadas a ela até que você selecione outra conta:

// 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 Search and Display campaigns under the client account
  const campaignIterator = AdsApp.campaigns().get();

  // Operate on client account
  ...
}

Trabalhar em contas em paralelo

Os scripts do Google Ads permitem operar em várias contas de cliente em paralelo usando o executeInParallel método da ManagedAccountSelector classe. 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 que o ManagedAccountSelector corresponde. Depois que todas as contas forem processadas, a função de callback, se especificada por optionalCallbackFunctionName, será executada uma vez, transmitindo uma lista de ExecutionResult objetos como argumento para qualquer outro processamento. O uso típico é mostrado aqui:

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 um parâmetro adicional 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.
  ...
}

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

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 ExecutionResult objetos. Se você retornou uma string JSON da função, pode convertê-la de volta em um objeto JavaScript usando JSON.parse método:

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

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

Limites de tempo de execução

Consulte a documentação de limites para mais detalhes sobre os limites de tempo de execução dos scripts do Google Ads.