Google Apps Script Library — Библиотеки в Гугл Скриптах

Правильный канал о Таблицах (Google Sheets): @google_sheets

Чат канала: @google_spreadsheets_chat

Здравствуйте, товарищи!

Сегодня маленькая простая статья − расскажем про библиотеки в Google Apps Script.

Ещё в древности людей задолбало копипастить один и тот же код по своим проектам, а потом по всем этим проектам бегать, чтобы поменять его. Решили писать (и обновлять) повторяющийся код в одном месте, и брать его напрямую оттуда. Место назвали библиотекой.

В Google Apps Script то же самое. Любой проект можно опубликовать в виде библиотеки и пользоваться повсеместно, с друзьями поделиться.

Создаём проект

Идём сюда https://script.google.com/ и создаём новый проект. Это будет отдельно стоящий (standalone) проект, то есть он не привязан ни к какому контейнеру (Container-bound) (таблице, документу, форме и пр.).

Пишем простой код:

Logger.log('Inside library - START');

function SPREADSHEETID() {
  return SpreadsheetApp.getActiveSpreadsheet().getId();
}

Logger.log('Inside library - END');

Что делает код?

Logger.log(...) просто выводит сообщение в лог. Мы это делаем в начале и в конце для наглядности, посмотрим позже.

Ещё мы определяем функцию SPREADSHEETID(), которая возвращает Id текущей таблицы. Сейчас таблицы нет, но мы библиотеку подключим к проекту, привязанному к таблице, и будем пользоваться.

Публикуем библиотеку

Надо нажать пару кнопок.

Библиотека опубликована. Для её использования в других проектах нужен Id и номер версии. Опубликованные версии можно посмотреть там же, а Id можно скопировать на последнем окне при публикации, взять из ссылки в браузере или в настройках проекта:

Если библиотекой будете пользоваться только в своих проектах, то этого достаточно. Если доступ к ней необходимо дать другим людям, надо пошарить проект. Вот я, например, выдаю доступ на просмотр (этого достаточно для использования) всем подряд:

Импортируем библиотеку

Создаём новую таблицу (в Chrome можно просто набрать sheets.new), и открываем редактор скриптов:

Id библиотеки у нас скопирован:

Используем библиотеку

Библиотека подключена можно использовать. Почти ко всему, что в ней есть, можно обратиться следующим образом testlib.что-то.

Если что-то не нужно выставлять наружу из библиотеки, то имя переменной или функции должно заканчиваться на подчерк (_). Такие переменные и функции, можно использовать внутри библиотеки, но testlib.что-то_ в проекте, который подключил библиотеку, работать не будет.

Оформим нашу библиотечную функцию в пользовательскую функцию:

/**
 * @OnlyCurrentDoc
 */

/**
 * Returns current Spreadsheet's ID.
 *
 * @returns Current Spreadsheet's ID (a scary part of the URL).
 * @customfunction
 */
function GETID() {
  return testlib.SPREADSHEETID();
}

Теперь можно использовать функцию в таблице:

Замечания

Для начала посмотрим логи:

Как видно, сначала инициализируются библиотеки, то есть выполняются все statement'ы верхнего уровня. У нас там в начале и в конце была запись в лог − их и наблюдаем. Потом инициализируется локальный скрипт (на скрине выше видно, что я туда тоже добавил запись в лог). И только потом что-то выполняется, конкретно пользовательская функция.

Библиотека будет проинициализирована, если подключена, независимо от того, используете вы её фактически или нет. Так что аккуратнее с тем, что подключаете − сначала изучите исходники.

Ещё на инициализацию библиотек уходит драгоценное время, часть этих 6 минут (или 30 секунд в случае пользовательской функции). Это тоже стоит учитывать. Особенно, если у вас там целая цепочка библиотек тянется, и все друг друга инициализируют.

Товарищ Виталий подсказывает, что стоит заметить: библиотека не подойдёт, чтобы спрятать код.

Если у вас Id библиотеки, то посмотреть её код можно пройдя по ссылке ({Id}, понятно, надо заменить):

https://script.google.com/d/{Id}/edit

В начале кода проекта есть такое:

/**
 * @OnlyCurrentDoc
 */

Это автоматом даёт скрипту разрешение для работы только с текущей таблицей. Иначе надо было бы явно прописывать oauthScopes в appsscript.json.

Ещё товарищ Намоконов даёт совет для отладки.

Если вы отлаживаетесь, то чтобы не переопубликовывать (словечко!) библиотеку каждый раз, можно при импорте выбрать версию HEAD, но такой фокус пройдёт только с вашими библиотеками (может, еще с пошаренными на редактирование):

Не используйте HEAD в проектах, к которым есть доступ у других людей. У них по факту или последняя опубликованная версия будет использоваться, или вообще работать не будет. Только для отладки.

На этом всё. Спасибо за внимание.

Берегите себя, не болейте.

Ссылки

Google Apps Script

• Вообще всё это есть в родной документации на Apps Script
• Про скрипты, привязанные к контейнеру, и про отдельно стоящие
• Про разрешения и про oauthScopes
• Конкретно про @OnlyCurrentDoc
• Про библиотеки
• Очень важно про то, какие части проекта, который использует библиотеку, видны в библиотеке

Правильный канал о Таблицах (Google Sheets): @google_sheets

Чат канала: @google_spreadsheets_chat