застежка — интерфейс командной строки сценариев приложений

1. Введение

Инструмент командной строки Apps Script, или clasp , позволяет создавать, редактировать и развертывать проекты Apps Script локально. Он позволяет создавать и публиковать веб-приложения и дополнения для таких продуктов, как Sheets, Docs, Forms и Slides, из командной строки. Существует два способа разработки Apps Script: с помощью script.google.com или локально на вашем компьютере. Мы изучим второй способ, а именно, как использовать clasp — инструмент командной строки для Apps Script.

Функции

• Разрабатывайте локально. clasp позволяет писать код на собственном компьютере и загружать его в Apps Script после завершения работы. Вы также можете загрузить существующие проекты Apps Script и редактировать их локально. После того, как код окажется локально, вы можете использовать свои любимые инструменты разработки, такие как git, для работы над проектами Apps Script.
• Управление версиями развертывания . Создавайте, обновляйте и просматривайте несколько развертываний вашего проекта.
• Структура кода. clasp автоматически преобразует ваш плоский проект на script.google.com в папки . Например:

# On script.google.com:
├── tests/slides.gs
└── tests/sheets.gs

# Locally:
├── tests/
│   ├─ slides.gs
│   └─ sheets.gs

Что вы узнаете

В этом практическом занятии вы узнаете, как реализовать 3 ключевых действия с помощью clasp :

• Как создавать новые проекты Apps Script
• Как клонировать, получать и отправлять существующие проекты
• Как управлять развертыванием ваших скриптов

2. Начало работы

Загрузка интерфейса командной строки

Для работы Apps Script CLI ( clasp ) требуется установленный Node.js. Установить Node.js можно здесь .

Примечание: для работы clasp требуется Node.js >= 20.0.0 . Обновите Node.js с помощью следующих команд:

sudo npm install n -g

sudo n latest

После установки Node.js установите CLI глобально (псевдоним clasp ):

npm i @google/clasp -g

3. Включите API Apps Script.

Прежде чем использовать Clasp, необходимо включить API Google Apps Script в среде разработки Apps Script IDE.

4. Вход в систему

Авторизоваться

Давайте попробуем команду clasp ! Единственная команда, которую вам нужно запомнить, это clasp .

clasp

Мы установили clasp глобально на нашем компьютере, поэтому команда должна работать везде в вашей файловой системе.

Прежде чем начать использовать инструмент командной строки, необходимо войти в систему. Выполните следующую команду:

clasp login

или при использовании SSH:

clasp login --no-localhost

На этом этапе вам будет предложено войти в Google. Все проекты, созданные с помощью CLI, будут связаны с этой учетной записью Google.

5. Создайте новый проект

Создайте автономный проект

Для начала создайте автономный проект Google Apps Script с помощью следующей команды:

mkdir clasp_codelab;
cd clasp_codelab;
clasp create --title "Clasp Codelab"  --type standalone;

Вы только что создали проект Apps Script в папке "clasp_codelab"!

Примечание: Команда clasp create создала автономный скрипт. Это означает, что проект не связан с таблицей Google Sheets, документом Google Docs, формой Google Forms или презентацией. Однако, как создать связанный скрипт, мы рассмотрим в следующем разделе.

(Дополнительный вариант) Клонировать существующий проект

Давайте попробуем создать скрипт , привязанный к контейнеру, для дополнения Google Slides.

Для этого перейдите на slides.google.com и создайте новую презентацию. Измените название презентации на " clasp Codelab Test ". В строке меню Slides, в меню " Расширения" , выберите " Apps Script ".

Это откроет ваш проект Apps Script по адресу script.google.com .

Создайте новую директорию для вашего проекта и перейдите в неё с cd .

mkdir clasp_codelab_test
cd clasp_codelab_test

Для клонирования проекта нам нужен Script ID ). Этот идентификатор можно найти в URL-адресе проекта Apps Script по адресу /projects/ . Скопируйте значение и вставьте его в следующую команду:

clasp clone <scriptID>

Результат должен выглядеть примерно так...

Теперь проект загружен в текущую директорию . Используйте свой любимый редактор, чтобы просмотреть содержимое файла Code.gs (пустая функция).

6. Передача и извлечение файлов

Отредактируйте код на script.google.com

Теперь, когда вы умеете клонировать проект, давайте научимся загружать и отправлять файлы. Мы шаг за шагом расскажем вам, как редактировать файлы в облаке через script.google.com и загружать их локально на ваш компьютер. Давайте откроем скрипт в облаке:

clasp open-script

Теперь, когда мы находимся в онлайн-редакторе, мы отредактируем код в режиме онлайн, который позже получим с помощью clasp .

Чтобы создать новый файл Apps Script, слева от редактора, рядом с кнопкой «Файлы» , нажмите «Добавить файл». > Скрипт . Введите имя utils/strings . В созданном файле utils/strings.gs замените код следующим:

var world = "世界";

В Code.gs замените существующий код следующим:

function hello() {
  Logger.log("Hello, " + world);
}

Вверху нажмите «Сохранить». .

Чтобы запустить функцию, в верхней части редактора выберите hello из выпадающего списка функций и нажмите «Запустить» .

Приветствие отображается внизу журнала выполнения.

Редактируйте код локально.

Вернемся к командной строке, где мы в последний раз клонировали проект. Вы можете заметить, что наш код теперь не синхронизирован с онлайн-редактором. Чтобы это исправить, давайте скопируем код из нашего онлайн-проекта.

clasp pull

Теперь вернитесь к коду. Вы должны заметить, что там есть папка для наших утилит. Интерфейс командной строки clasp автоматически преобразует символ косой черты / в названия папок в локальной файловой системе.

В вашем любимом текстовом редакторе перейдите в файл util/strings.gs и замените имя переменной world на mondo . Также обновите файл Code.gs, заменив world на mondo . Чтобы обновить код на script.google.com , загрузите отредактированный код.

clasp push

Вот и всё! Ваш код теперь обновлён на script.google.com .

Команда clasp push заменяет код, находящийся на `script.google.com`, а clasp pull заменяет все локальные файлы. Поэтому следуйте этим рекомендациям:

• Не следует одновременно редактировать код локально и на script.google.com .
• Используйте систему контроля версий, например, Git .

7. Версионирование и развертывание

clasp позволяет управлять версиями и развертываниями. Для начала немного терминологии:

• Версия : «Снимок» проекта скрипта. Версию можно рассматривать как ветку только для чтения, используемую для развертывания.
• Развертывание : Опубликованный релиз скриптового проекта (часто в виде дополнения или веб-приложения). Требуется номер версии.

Давайте создадим версию нашего скрипта:

clasp create-version "First version"

Используя созданную нами строку версии, содержащую текст в логе, вместо [version] , мы можем развернуть скрипт:

clasp create-deployment 1 "First deployment"

Команда clasp deploy анализирует ваш манифест и создает новое версионированное развертывание. Ваш код теперь развернут как исполняемый файл. Подробнее об этом можно узнать в руководстве по развертыванию .

8. Вот и всё!

Мы надеемся, что интерфейс командной строки Apps Script станет простым инструментом, который поможет вам управлять проектами Apps Script.

Что мы рассмотрели

• Как создавать новые проекты Apps Script
• Как клонировать, отправлять и получать существующие проекты
• Как управлять развертыванием ваших скриптов

Clasp доступен на GitHub , и мы будем рады новым функциям и исправлениям.

Нам не терпится увидеть, что вы построите!