Executar funções com a API Google Apps Script

A API Apps Script fornece um scripts.run método que executa remotamente uma função especificada do Google Apps Script. É possível usar esse método em um aplicativo de chamada para executar uma função em um dos seus projetos de script remotamente e receber uma resposta.

Requisitos

Antes que um aplicativo de chamada possa usar o scripts.run método, você deve:

O método scripts.run

O método scripts.run exige as seguintes informações:

Opcionalmente, é possível configurar o script para execução no modo de desenvolvimento. Esse modo é executado com a versão salva mais recente do projeto de script, em vez da versão implantada mais recentemente. Para fazer isso, defina o devMode booleano no corpo da solicitação como true. Somente o proprietário do script pode executá-lo no modo de desenvolvimento.

Processar tipos de dados de parâmetros

O uso do método da API Apps Script scripts.run geralmente envolve o envio de dados para o Apps Script como parâmetros de função e o recebimento de dados como valores de retorno de função. A API só pode receber e retornar valores com tipos básicos: strings, matrizes, objetos, números e booleanos. Objetos mais complexos do Apps Script, como Document ou Sheet, não podem ser transmitidos para ou do projeto de script pela API.

Quando o aplicativo de chamada é escrito em uma linguagem fortemente tipada, como Java, ele transmite parâmetros como uma lista ou matriz de objetos genéricos correspondentes a esses tipos básicos. Em muitos casos, é possível aplicar conversões de tipo automaticamente. Por exemplo, uma função que usa um parâmetro numérico pode receber um objeto Double, Integer ou Long do Java como um parâmetro sem processamento extra.

Quando a API retorna a resposta da função, geralmente é necessário converter o valor retornado para o tipo correto antes que ele possa ser usado. Confira alguns exemplos baseados em Java:

  • Os números retornados pela API para um aplicativo Java chegam como objetos java.math.BigDecimal e podem precisar ser convertidos em tipos Double ou int.
  • Se a função do Apps Script retornar uma matriz de strings, um aplicativo Java vai converter a resposta em um List<String> objeto:

    List<String> mylist = (List<String>)(op.getResponse().get("result"));
    
  • Se você quiser retornar uma matriz de Bytes, codifique a matriz como uma string base64 na função do Apps Script e retorne essa string:

    return Utilities.base64Encode(myByteArray); // returns a string.
    

Os exemplos de código abaixo ilustram maneiras de interpretar a resposta da API.

Procedimento geral

Para usar a API Apps Script para executar funções do Apps Script, siga estas etapas:

Etapa 1: configurar o projeto na nuvem comum

O script e o aplicativo de chamada precisam compartilhar o mesmo projeto na nuvem. Esse projeto na nuvem pode ser um projeto atual ou um novo projeto criado para essa finalidade. Depois de ter um projeto na nuvem, é necessário mudar o projeto de script para usá-lo.

Etapa 2: implantar o script como um executável de API

  1. Abra o projeto do Apps Script com as funções que você quer usar.
  2. No canto superior direito, clique em Implantar > Nova implantação.
  3. Na caixa de diálogo que é aberta, clique em Ativar tipos de implantação > Executável de API.
  4. No menu suspenso "Quem tem acesso", selecione os usuários que podem chamar as funções do script usando a API Apps Script.
  5. Clique em Implantar.

Etapa 3: configurar o aplicativo de chamada

O aplicativo de chamada precisa ativar a API Apps Script e estabelecer credenciais OAuth antes do uso. É necessário ter acesso ao projeto na nuvem para fazer isso.

  1. Configure o projeto na nuvem que o aplicativo de chamada e o script estão usando:
    1. Ative a API Apps Script no projeto na nuvem.
    2. Configure a tela de permissão OAuth.
    3. Crie credenciais do OAuth.
  2. Abra o projeto de script e, à esquerda, clique em Visão geral .
  3. Em Escopos OAuth do projeto, registre todos os escopos exigidos pelo script.
  4. No código do aplicativo de chamada, gere um token de acesso OAuth de script para a chamada de API. Esse não é um token usado pela API, mas sim um que o script exige ao ser executado. Ele precisa ser criado usando o ID do cliente do projeto na nuvem e os escopos de script registrados.

    As bibliotecas de cliente do Google podem ajudar a criar esse token e processar o OAuth para o aplicativo, geralmente permitindo que você crie um objeto de "credenciais" de nível superior usando os escopos de script. Consulte os guias de início rápido da API Apps Script para exemplos de como criar um objeto de credenciais em uma lista de escopos.

Etapa 4: fazer a solicitação scripts.run

Depois que o aplicativo de chamada for configurado, você poderá fazer scripts.run chamadas:

  1. Crie uma solicitação de API usando o ID de implantação, o nome da função e todos os parâmetros necessários.
  2. Faça a scripts.run chamada e inclua o token OAuth de script criado no cabeçalho (se estiver usando uma solicitação POST básica) ou use um objeto de credenciais criado com os escopos de script.
  3. Permita que o script termine a execução. Os scripts podem levar até seis minutos de tempo de execução. Portanto, o aplicativo precisa permitir isso.
  4. Ao terminar, a função de script poderá retornar um valor, que a API vai entregar de volta ao aplicativo se o valor for um tipo compatível.

É possível encontrar exemplos de scripts.run chamadas de API na seção a seguir.

Para atualizar o token de acesso, adicione o snippet a seguir antes da solicitação de API scripts.run:

if (credential.getExpiresInSeconds() <= 360) {
  credential.refreshToken();
}

Exemplos de solicitações de API

Os exemplos a seguir mostram como fazer uma solicitação de execução da API Apps Script em várias linguagens, chamando uma função do Apps Script para imprimir uma lista de pastas no diretório raiz do usuário. O ID de implantação do projeto do Apps Script que contém a função executada precisa ser especificado onde indicado com ENTER_YOUR_DEPLOYMENT_ID_HERE. Os exemplos dependem das bibliotecas de cliente da API do Google.

Script de destino

A função neste script usa a API Drive.

É necessário ativar a API Drive no projeto que hospeda o script.

Além disso, os aplicativos de chamada precisam enviar credenciais OAuth que incluem o seguinte escopo do Drive:

  • https://www.googleapis.com/auth/drive

Os aplicativos de exemplo aqui usam as bibliotecas de cliente do Google para criar objetos de credenciais para OAuth usando esse escopo.

/**
 * Return the set of folder names contained in the user's root folder as an
 * object (with folder IDs as keys).
 * @return {Object} A set of folder names keyed by folder ID.
 */
function getFoldersUnderRoot() {
  const root = DriveApp.getRootFolder();
  const folders = root.getFolders();
  const folderSet = {};
  while (folders.hasNext()) {
    const folder = folders.next();
    folderSet[folder.getId()] = folder.getName();
  }
  return folderSet;
}

Java


/**
 * Create a HttpRequestInitializer from the given one, except set
 * the HTTP read timeout to be longer than the default (to allow
 * called scripts time to execute).
 *
 * @param {HttpRequestInitializer} requestInitializer the initializer
 *                                 to copy and adjust; typically a Credential object.
 * @return an initializer with an extended read timeout.
 */
private static HttpRequestInitializer setHttpTimeout(
    final HttpRequestInitializer requestInitializer) {
  return new HttpRequestInitializer() {
    @Override
    public void initialize(HttpRequest httpRequest) throws IOException {
      requestInitializer.initialize(httpRequest);
      // This allows the API to call (and avoid timing out on)
      // functions that take up to 6 minutes to complete (the maximum
      // allowed script run time), plus a little overhead.
      httpRequest.setReadTimeout(380000);
    }
  };
}

/**
 * Build and return an authorized Script client service.
 *
 * @param {Credential} credential an authorized Credential object
 * @return an authorized Script client service
 */
public static Script getScriptService() throws IOException {
  Credential credential = authorize();
  return new Script.Builder(
      HTTP_TRANSPORT, JSON_FACTORY, setHttpTimeout(credential))
      .setApplicationName(APPLICATION_NAME)
      .build();
}

/**
 * Interpret an error response returned by the API and return a String
 * summary.
 *
 * @param {Operation} op the Operation returning an error response
 * @return summary of error response, or null if Operation returned no
 * error
 */
public static String getScriptError(Operation op) {
  if (op.getError() == null) {
    return null;
  }

  // Extract the first (and only) set of error details and cast as a Map.
  // The values of this map are the script's 'errorMessage' and
  // 'errorType', and an array of stack trace elements (which also need to
  // be cast as Maps).
  Map<String, Object> detail = op.getError().getDetails().get(0);
  List<Map<String, Object>> stacktrace =
      (List<Map<String, Object>>) detail.get("scriptStackTraceElements");

  java.lang.StringBuilder sb =
      new StringBuilder("\nScript error message: ");
  sb.append(detail.get("errorMessage"));
  sb.append("\nScript error type: ");
  sb.append(detail.get("errorType"));

  if (stacktrace != null) {
    // There may not be a stacktrace if the script didn't start
    // executing.
    sb.append("\nScript error stacktrace:");
    for (Map<String, Object> elem : stacktrace) {
      sb.append("\n  ");
      sb.append(elem.get("function"));
      sb.append(":");
      sb.append(elem.get("lineNumber"));
    }
  }
  sb.append("\n");
  return sb.toString();
}

public static void main(String[] args) throws IOException {
  // ID of the script to call. Acquire this from the Apps Script editor,
  // under Publish > Deploy as API executable.
  String scriptId = "ENTER_YOUR_SCRIPT_ID_HERE";
  Script service = getScriptService();

  // Create an execution request object.
  ExecutionRequest request = new ExecutionRequest()
      .setFunction("getFoldersUnderRoot");

  try {
    // Make the API request.
    Operation op =
        service.scripts().run(scriptId, request).execute();

    // Print results of request.
    if (op.getError() != null) {
      // The API executed, but the script returned an error.
      System.out.println(getScriptError(op));
    } else {
      // The result provided by the API needs to be cast into
      // the correct type, based upon what types the Apps
      // Script function returns. Here, the function returns
      // an Apps Script Object with String keys and values,
      // so must be cast into a Java Map (folderSet).
      Map<String, String> folderSet =
          (Map<String, String>) (op.getResponse().get("result"));
      if (folderSet.size() == 0) {
        System.out.println("No folders returned!");
      } else {
        System.out.println("Folders under your root folder:");
        for (String id : folderSet.keySet()) {
          System.out.printf(
              "\t%s (%s)\n", folderSet.get(id), id);
        }
      }
    }
  } catch (GoogleJsonResponseException e) {
    // The API encountered a problem before the script was called.
    e.printStackTrace(System.out);
  }
}

JavaScript

/**
 * Load the API and make an API call.  Display the results on the screen.
 */
function callScriptFunction() {
  const scriptId = '<ENTER_YOUR_SCRIPT_ID_HERE>';

  // Call the Apps Script API run method
  //   'scriptId' is the URL parameter that states what script to run
  //   'resource' describes the run request body (with the function name
  //              to execute)
  try {
    gapi.client.script.scripts.run({
      'scriptId': scriptId,
      'resource': {
        'function': 'getFoldersUnderRoot',
      },
    }).then(function(resp) {
      const result = resp.result;
      if (result.error && result.error.status) {
        // The API encountered a problem before the script
        // started executing.
        appendPre('Error calling API:');
        appendPre(JSON.stringify(result, null, 2));
      } else if (result.error) {
        // The API executed, but the script returned an error.

        // Extract the first (and only) set of error details.
        // The values of this object are the script's 'errorMessage' and
        // 'errorType', and an array of stack trace elements.
        const error = result.error.details[0];
        appendPre('Script error message: ' + error.errorMessage);

        if (error.scriptStackTraceElements) {
          // There may not be a stacktrace if the script didn't start
          // executing.
          appendPre('Script error stacktrace:');
          for (let i = 0; i < error.scriptStackTraceElements.length; i++) {
            const trace = error.scriptStackTraceElements[i];
            appendPre('\t' + trace.function + ':' + trace.lineNumber);
          }
        }
      } else {
        // The structure of the result will depend upon what the Apps
        // Script function returns. Here, the function returns an Apps
        // Script Object with String keys and values, and so the result
        // is treated as a JavaScript object (folderSet).

        const folderSet = result.response.result;
        if (Object.keys(folderSet).length == 0) {
          appendPre('No folders returned!');
        } else {
          appendPre('Folders under your root folder:');
          Object.keys(folderSet).forEach(function(id) {
            appendPre('\t' + folderSet[id] + ' (' + id + ')');
          });
        }
      }
    });
  } catch (err) {
    document.getElementById('content').innerText = err.message;
    return;
  }
}

Node.js


import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Calls an Apps Script function to list the folders in the user's root Drive folder.
 */
async function callAppsScript() {
  // The ID of the Apps Script project to call.
  const scriptId = '1xGOh6wCm7hlIVSVPKm0y_dL-YqetspS5DEVmMzaxd_6AAvI-_u8DSgBT';

  // Authenticate with Google and get an authorized client.
  // TODO (developer): Use an appropriate auth mechanism for your app.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Apps Script API client.
  const script = google.script({version: 'v1', auth});

  const resp = await script.scripts.run({
    auth,
    requestBody: {
      // The name of the function to call in the Apps Script project.
      function: 'getFoldersUnderRoot',
    },
    scriptId,
  });

  if (resp.data.error?.details?.[0]) {
    // The API executed, but the script returned an error.
    // Extract the error details.
    const error = resp.data.error.details[0];
    console.log(`Script error message: ${error.errorMessage}`);
    console.log('Script error stacktrace:');

    if (error.scriptStackTraceElements) {
      // Log the stack trace.
      for (let i = 0; i < error.scriptStackTraceElements.length; i++) {
        const trace = error.scriptStackTraceElements[i];
        console.log('\t%s: %s', trace.function, trace.lineNumber);
      }
    }
  } else {
    // The script executed successfully.
    // The structure of the response depends on the Apps Script function's return value.
    const folderSet = resp.data.response ?? {};
    if (Object.keys(folderSet).length === 0) {
      console.log('No folders returned!');
    } else {
      console.log('Folders under your root folder:');
      Object.keys(folderSet).forEach((id) => {
        console.log('\t%s (%s)', folderSet[id], id);
      });
    }
  }
}

Python

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def main():
  """Runs the sample."""
  # pylint: disable=maybe-no-member
  script_id = "1VFBDoJFy6yb9z7-luOwRv3fCmeNOzILPnR4QVmR0bGJ7gQ3QMPpCW-yt"

  creds, _ = google.auth.default()
  service = build("script", "v1", credentials=creds)

  # Create an execution request object.
  request = {"function": "getFoldersUnderRoot"}

  try:
    # Make the API request.
    response = service.scripts().run(scriptId=script_id, body=request).execute()
    if "error" in response:
      # The API executed, but the script returned an error.
      # Extract the first (and only) set of error details. The values of
      # this object are the script's 'errorMessage' and 'errorType', and
      # a list of stack trace elements.
      error = response["error"]["details"][0]
      print(f"Script error message: {0}.{format(error['errorMessage'])}")

      if "scriptStackTraceElements" in error:
        # There may not be a stacktrace if the script didn't start
        # executing.
        print("Script error stacktrace:")
        for trace in error["scriptStackTraceElements"]:
          print(f"\t{0}: {1}.{format(trace['function'], trace['lineNumber'])}")
    else:
      # The structure of the result depends upon what the Apps Script
      # function returns. Here, the function returns an Apps Script
      # Object with String keys and values, and so the result is
      # treated as a Python dictionary (folder_set).
      folder_set = response["response"].get("result", {})
      if not folder_set:
        print("No folders returned!")
      else:
        print("Folders under your root folder:")
        for folder_id, folder in folder_set.items():
          print(f"\t{0} ({1}).{format(folder, folder_id)}")

  except HttpError as error:
    # The API encountered a problem before the script started executing.
    print(f"An error occurred: {error}")
    print(error.content)


if __name__ == "__main__":
  main()

Limitações

A API Apps Script tem as seguintes limitações:

  1. Um projeto na nuvem comum. O script que está sendo chamado e o aplicativo de chamada precisam compartilhar um projeto na nuvem. O projeto na nuvem precisa ser um projeto padrão na nuvem. Os projetos padrão criados para projetos do Apps Script não são suficientes.

  2. Tipos básicos de parâmetros e retorno. A API não pode transmitir ou retornar objetos específicos do Apps Script (como documentos, blobs, agendas, arquivos do Drive etc.) para o aplicativo. Somente tipos básicos, como strings, matrizes, objetos, números e booleanos, podem ser transmitidos e retornados.

  3. Escopos do OAuth. A API só pode executar scripts que tenham pelo menos um escopo necessário. Isso significa que não é possível usar a API para chamar um script que não exige a autorização de um ou mais serviços.

  4. Sem acionadores. A API não pode criar acionadores do Apps Script .