Выполнение функций с помощью Apps Script API

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Google Apps Script API предоставляет метод scripts.run , который удаленно выполняет указанную функцию Apps Script. Вы можете использовать этот метод в вызывающем приложении для удаленного запуска функции в одном из ваших проектов сценариев и получения ответа.

Требования

Вы должны выполнить следующие требования, прежде чем вызывающее приложение сможет использовать метод scripts.run . Вы должны :

  • Разверните проект скрипта как исполняемый файл API. Вы можете развертывать, отменять развертывание и повторно развертывать проекты по мере необходимости.

  • Предоставьте токен OAuth с правильной областью действия для выполнения. Этот токен OAuth должен охватывать все области , используемые сценарием, а не только те, которые используются вызываемой функцией. См. полный список областей авторизации в справочнике по методам.

  • Убедитесь, что сценарий и клиент OAuth2 вызывающего приложения совместно используют общий проект Google Cloud. Облачный проект должен быть стандартным облачным проектом ; проектов по умолчанию, созданных для проектов Apps Script, недостаточно. Вы можете использовать новый стандартный облачный проект или уже существующий.

  • Включите Google Apps Script API в облачном проекте.

Метод scripts.run

Для запуска метода scripts.run требуется информация, идентифицирующая ключ:

При желании вы можете настроить свой сценарий для выполнения в режиме разработки . Этот режим выполняется с самой последней сохраненной версией проекта скрипта, а не с самой последней развернутой версией. Для этого установите для логического devMode в теле запроса значение true . Только владелец скрипта может выполнить его в режиме разработки.

Обработка типов данных параметров

Использование метода scripts.run API скриптов приложений обычно включает отправку данных в скрипт приложений в виде параметров функции и возврат данных в качестве возвращаемых значений функции. API может принимать и возвращать значения только базовых типов: строки, массивы, объекты, числа и логические значения. Они похожи на основные типы в JavaScript. Более сложные объекты Apps Script, такие как Document или Sheet , не могут быть переданы в проект скрипта или из него с помощью API.

Когда вызывающее приложение написано на языке со строгим типом, таком как Java, оно передает параметры в виде списка или массива универсальных объектов, соответствующих этим базовым типам. Во многих случаях можно автоматически применять простые преобразования типов. Например, функции, которая принимает числовой параметр, можно передать объект Java Double , Integer или Long в качестве параметра без дополнительной обработки.

Когда API возвращает ответ функции, вам часто нужно привести возвращаемое значение к правильному типу, прежде чем его можно будет использовать. Вот несколько примеров на основе Java:

  • Числа, возвращаемые API в приложение Java, поступают в виде объектов java.math.BigDecimal , и при необходимости их может потребоваться преобразовать в типы Doubles или int .
  • Если функция Apps Script возвращает массив строк, приложение Java преобразует ответ в объект List<String> :

    List<String> mylist = (List<String>)(op.getResponse().get("result"));
    
  • Если вы хотите вернуть массив Bytes , вам может оказаться удобным закодировать массив как строку base64 в функции Apps Script и вместо этого вернуть эту строку:

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

Примеры кода ниже иллюстрируют способы интерпретации ответа API.

Общая процедура

Ниже описана общая процедура использования Apps Script API для выполнения функций Apps Script.

Шаг 1. Настройте общий облачный проект

И ваш скрипт, и вызывающее приложение должны использовать один и тот же облачный проект. Этот облачный проект может быть существующим проектом или новым проектом, созданным для этой цели. Если у вас есть облачный проект, вы должны переключить проект скрипта, чтобы использовать его .

Шаг 2. Разверните скрипт как исполняемый файл API

  1. Откройте проект Apps Script с функциями, которые вы хотите использовать.
  2. В правом верхнем углу нажмите Развернуть > Новое развертывание .
  3. В открывшемся диалоговом окне нажмите Включить типы развертывания. > Исполняемый файл API .
  4. В раскрывающемся меню «У кого есть доступ» выберите пользователей, которым разрешено вызывать функции скрипта с помощью Apps Script API.
  5. Щелкните Развернуть .

Шаг 3. Настройте вызывающее приложение

Вызывающее приложение должно включить Apps Script API и установить учетные данные OAuth, прежде чем его можно будет использовать. Для этого у вас должен быть доступ к облачному проекту.

  1. Настройте облачный проект, который использует вызывающее приложение и сценарий. Вы можете сделать это, выполнив следующие действия:
    1. Включите Apps Script API в облачном проекте .
    2. Настройте экран согласия OAuth .
    3. Создайте учетные данные OAuth .
  2. Откройте проект скрипта и слева нажмите Обзор .
  3. В разделе «Области проекта Oauth » запишите все области, которые требуются сценарию.
  4. В коде вызывающего приложения создайте маркер доступа OAuth скрипта для вызова API. Это не токен, который использует сам API, а токен, который требуется сценарию при выполнении. Он должен быть создан с использованием идентификатора клиента облачного проекта и записанных вами областей скрипта.

    Клиентские библиотеки Google могут значительно помочь в создании этого токена и обработке OAuth для приложения, обычно позволяя вместо этого создавать объект «учетных данных» более высокого уровня, используя области скрипта. Примеры создания объекта учетных данных из списка областей см. в кратких руководствах по Apps Script API .

Шаг 4: Сделайте запрос script.run

После настройки вызывающего приложения вы можете выполнять вызовы scripts.run . Каждый вызов API состоит из следующих шагов:

  1. Создайте запрос API , используя идентификатор скрипта, имя функции и любые необходимые параметры.
  2. Сделайте вызов scripts.run и включите токен OAuth скрипта, который вы создали в заголовке (если используете базовый запрос POST ), или же используйте объект учетных данных, который вы создали с помощью областей скрипта.
  3. Разрешить скрипту завершить выполнение. Сценарии могут выполняться до шести минут, поэтому ваше приложение должно это учитывать.
  4. По завершении функция скрипта может вернуть значение, которое API возвращает обратно в приложение, если значение имеет поддерживаемый тип.

Вы можете найти примеры вызовов API script.run ниже.

Примеры запросов API

В следующих примерах показано, как сделать запрос на выполнение Apps Script API на разных языках, вызывая функцию Apps Script для вывода списка папок в корневом каталоге пользователя. Идентификатор сценария проекта Apps Script, содержащего выполняемую функцию, должен быть указан там, где он указан с помощью ENTER_YOUR_SCRIPT_ID_HERE . Примеры основаны на клиентских библиотеках Google API для соответствующих языков.

Целевой сценарий

Функция в этом скрипте использует Drive API.

Вы должны включить Drive API в проекте, в котором размещается скрипт.

Кроме того, вызывающие приложения должны отправлять учетные данные OAuth, которые включают следующую область Диска:

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

Примеры приложений здесь используют клиентские библиотеки Google для создания объектов учетных данных для OAuth с использованием этой области.

/**
 * 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;
}

Ява


/**
 * 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

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

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const script = google.script({version: 'v1', auth});

  try {
    // Make the API request. The request object is included here as 'resource'.
    const resp = await script.scripts.run({
      auth: auth,
      resource: {
        function: 'getFoldersUnderRoot',
      },
      scriptId: scriptId,
    });
    if (resp.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 = resp.error.details[0];
      console.log('Script error message: ' + error.errorMessage);
      console.log('Script error stacktrace:');

      if (error.scriptStackTraceElements) {
        // There may not be a stacktrace if the script didn't start executing.
        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 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
      // Node.js object (folderSet).
      const folderSet = resp.response.result;
      if (Object.keys(folderSet).length == 0) {
        console.log('No folders returned!');
      } else {
        console.log('Folders under your root folder:');
        Object.keys(folderSet).forEach(function(id) {
          console.log('\t%s (%s)', folderSet[id], id);
        });
      }
    }
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

питон

from __future__ import print_function

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}."
                          f"{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()

Ограничения

Apps Script API имеет несколько ограничений:

  1. Обычный облачный проект . Вызываемый скрипт и вызывающее приложение должны совместно использовать облачный проект. Облачный проект должен быть стандартным облачным проектом ; проектов по умолчанию, созданных для проектов Apps Script, недостаточно. Стандартный облачный проект может быть новым или существующим.

  2. Основные параметры и возвращаемые типы . API не может передавать или возвращать приложению объекты, относящиеся к скрипту приложений (такие как документы , большие двоичные объекты , календари , файлы на диске и т. д.). Только основные типы, такие как строки, массивы, объекты, числа и логические значения, могут быть переданы и возвращены.

  3. Области действия OAuth . API может выполнять только те сценарии, которые имеют хотя бы одну требуемую область действия. Это означает, что вы не можете использовать API для вызова скрипта, который не требует авторизации одной или нескольких служб.

  4. Нет триггеров . API не может создавать триггеры сценариев приложений.