Что такое подключаемые файлы и зачем они нужны?
Подключаемые файлы (Shared Libraries) в Google Apps Script — это способ повторного использования кода в различных скриптах. Они позволяют выносить общие функции и классы в отдельные проекты, которые затем можно подключать к другим скриптам как библиотеки. Это значительно упрощает разработку, особенно когда необходимо использовать один и тот же код в нескольких проектах, например, при разработке дополнений для Google Workspace.
Преимущества использования подключаемых файлов (библиотек)
Повторное использование кода: Исключается дублирование кода, что упрощает поддержку и обновление.
Модульность: Код становится более организованным и легко поддерживаемым.
Улучшенная структура проекта: Логика проекта разделена на отдельные модули.
Централизованное обновление: Обновление библиотеки автоматически распространяется на все проекты, использующие её.
Отличия подключаемых файлов от обычных скриптов
Основное отличие заключается в том, что подключаемые файлы не выполняются напрямую. Они предоставляют функциональность, которую другие скрипты могут использовать. Обычные скрипты выполняются самостоятельно и могут вызывать функции из подключаемых файлов. Подключаемые файлы, по сути, являются библиотеками функций и классов, а не самостоятельными приложениями.
Создание и публикация подключаемого файла
Подготовка скрипта для публикации в качестве подключаемого файла
Прежде чем публиковать скрипт как подключаемый файл, убедитесь, что он содержит функции или классы, которые вы хотите использовать в других скриптах. Важно документировать код, используя комментарии, чтобы другим разработчикам было проще понять, как его использовать. Желательно использовать строгую типизацию (JSDoc) для параметров функций и возвращаемых значений.
/**
* Функция для расчета ROI (Return on Investment).
*
* @param {number} investment Сумма инвестиций.
* @param {number} revenue Сумма дохода.
* @returns {number} ROI в процентах.
*/
function calculateROI(investment: number, revenue: number): number {
if (investment === 0) {
throw new Error("Investment cannot be zero.");
}
return ((revenue - investment) / investment) * 100;
}Установка версий скрипта (Version Control)
Перед публикацией необходимо создать версию скрипта. Это позволяет отслеживать изменения и при необходимости вернуться к предыдущей версии. В редакторе Google Apps Script перейдите в Файл -> Управление версиями и создайте новую версию, указав описание изменений.
Публикация скрипта как подключаемого файла (Shared Libraries)
Перейдите в Файл -> Управление версиями и создайте версию.
Затем перейдите в Публикация -> Опубликовать как библиотеку.
Укажите имя библиотеки, описание и выберите версию, которую хотите опубликовать.
Настройте права доступа к библиотеке (кто может её использовать).
Нажмите Опубликовать.
После публикации вы получите идентификатор (Project key) подключаемого файла, который необходимо будет указать при подключении к другому проекту.
Управление версиями опубликованного подключаемого файла
При внесении изменений в библиотеку необходимо создавать новые версии и публиковать их. Разные проекты могут использовать разные версии библиотеки, что позволяет избежать проблем совместимости. Вы всегда можете вернуться к предыдущей версии, выбрав её при подключении библиотеки к проекту.
Использование подключаемого файла в другом скрипте
Добавление подключаемого файла в проект Google Apps Script
В редакторе Google Apps Script откройте проект, в который хотите добавить библиотеку.
Перейдите в Ресурсы -> Библиотеки.
В поле Найти библиотеку введите идентификатор (Project key) подключаемого файла.
Выберите нужную версию библиотеки.
Укажите алиас (имя, под которым библиотека будет доступна в вашем скрипте).
Нажмите Добавить.
Вызов функций из подключенного файла
После добавления библиотеки вы можете вызывать её функции, используя алиас, указанный при подключении.
// Предположим, что библиотека подключена с алиасом 'ROI_LIB'
function myFunction() {
const investment = 1000;
const revenue = 1500;
try {
const roi = ROI_LIB.calculateROI(investment, revenue);
Logger.log("ROI: " + roi + "%");
} catch (e) {
Logger.log("Error: " + e.message);
}
}Управление разрешениями и доступом к подключаемому файлу
При публикации библиотеки вы можете указать, кто может её использовать: только вы, только пользователи вашей организации или все пользователи. Убедитесь, что разрешения настроены правильно, чтобы избежать проблем с доступом.
Использование алиасов для подключаемых файлов
Алиас – это имя, под которым библиотека будет доступна в вашем скрипте. Выбор правильного алиаса упрощает чтение и понимание кода. Рекомендуется использовать алиасы, отражающие функциональность библиотеки.
Примеры использования подключаемых файлов
Подключаемый файл для работы с Google Sheets
Такая библиотека может содержать функции для чтения, записи и форматирования данных в Google Sheets. Например, функции для автоматического создания отчетов, выгрузки данных из API и т.д.
Подключаемый файл для отправки email-уведомлений
Библиотека, содержащая функции для отправки email-уведомлений с различными шаблонами и настройками. Позволяет централизованно управлять шаблонами писем и настройками отправки.
Подключаемый файл для интеграции с внешними API
Библиотека, содержащая функции для взаимодействия с различными API (например, Google Analytics, Google Ads). Позволяет упростить процесс аутентификации и обработки данных, получаемых из API.
Распространенные проблемы и их решения
Проблемы с версиями подключаемого файла
Если вы получаете ошибки, связанные с тем, что функция не найдена, убедитесь, что вы используете правильную версию библиотеки. Проверьте, что в вашем проекте подключена та версия библиотеки, которая содержит необходимую функцию.
Ошибки авторизации при использовании подключаемого файла
Если библиотека использует сервисы Google (например, Google Sheets, Gmail), убедитесь, что у вас есть необходимые разрешения для доступа к этим сервисам. В некоторых случаях может потребоваться повторная авторизация.
Отладка кода в подключаемом файле
Отладка кода в подключаемом файле может быть сложной, так как вы не можете напрямую запустить его из другого скрипта. Для отладки можно использовать Logger.log() для вывода отладочной информации или временно скопировать код библиотеки в основной скрипт для более удобной отладки.