CLI (Command Line Interface, zcli)
Назначение
CLI (Command Line Interface) — интерфейс командной строки, позволяющий управлять различными процессами объектного хранилища.
С Закрома.Хранение можно использовать стандартный AWS CLI, но использование zcli позволяет получить доступ к расширенному набору операций, присутствующему только в ЗАКРОМА.
ВниманиеВо всех командах, где необходимо указать какую-либо сложную конфигурацию нужно представлять её в виде строки параметров и их значений, разделенных запятой(
,) или точкой с запятой(;). Имя параметра должно быть отделено от его значения знаком равенства(=) или двоеточием(:), но, если значение какого-либо параметра может содержать двоеточие(:), то допускается только знак равенства(=)! Например:path=c:\mnt. Строка параметров может содержать пробелы для удобства чтения, но должна быть заключена в кавычки, чтобы интерпретатор команд воспринимал ее как одиночный параметр. Все подкоманды могут использоваться как в полном, так и в сокращенном виде.
Файл конфигурации
По умолчанию путь к конфигурационному файлу ~/.zakroma-config.yaml, который в Unix-подобных системах обычно находится в /home/$USER/.zakroma-config.yaml, а в Windows - C:\Users\%USER%\.zakroma-config.yaml.
Если использование файла конфигурации по умолчанию нежелательно, можно указать произвольный путь, как показано ниже:
1zcli --config some_path/local.yml 2zcli -c some_path/local.yml
Файл конфигурации может быть инициализирован с помощью подкоманды save-cfg следующим образом:
Для файла конфигурации по умолчанию:
1zcli save-cfg --server.proto https --server.host gateway.zakroma.ru --server.port 8081 --user Admin --password Password
Для файла конфигурации some_path/local.yml:
1 zcli --config some_path/local.yml save-cfg --server.proto https --server.host gateway.zakroma.ru --server.port 8081 --user Admin --password Password
Workspace (Рабочую область) и/или bucket можно добавить в конфигурацию с помощью опций —workspace и —bucket.
Workspace по умолчанию используется в подкомандах bucket. Также если в подкомандах object и bucket versioning не указывать workspace и bucket, то будут использоваться данные указанные в файле конфигурации. Сами Workspace и bucket также могут быть указаны в качестве переменных окружения.
При создании начального конфига:
1zcli save-cfg --server.proto https --server.host gateway.zakroma.ru --server.port 8081 --user admin --password passwd --w workspace-cli --b bucket-cli
При добавлении к уже существующему конфигу:
1zcli save-cfg --w workspace-cli --b bucket-cli
Если при создании конфигурации не задать —secret_key, то команда будет, при необходимости, пытаться получить ключ с сервера.
Формат команд
Работа с хранилищами
Создание хранилища S3 из командной строки.
Для создания нового хранилища s3 используется команда: storage create s3 —storage name=“Имя хранилища”, host=“Хост”, access_key=“Публичный ключ”, secret_key=“Секретный ключ”, ssl=“Использовать SSL: yes/no”,provider=“generic/yadro:
1zcli --config local.yml storage create s3 --storage "name=st0002, host=cloud.yandex.ru:8080, region=Moscow, access_key=somekey, secret_key=someotherkey,ssl=yes,provider=generic" 2zcli -c local.yml s c s3 --s "name=st0002, host=cloud.yandex.ru:8080, region=Moscow, access_key=somekey, secret_key=someotherkey,ssl=yes,provider=generic"
Создание хранилища агента из командной строки.
Для создания хранилища агента используется команда: storage create agent —storage “name=“Имя хранилища”, host=“Хост”, port=“Порт”, path=“Путь в файловом хранилище”, access_key=“Публичный ключ”, secret_key=“Секретный ключ”, ssl=“Использовать SSL: yes/no”:
1zcli --config local.yml storage create agent --storage "name=agent-presigned, host=agent.digital-spirit.ru, port=8080, path=c:/mnt, access_key=somekey1, secret_key=someotherkey, ssl=yes"
Создайте хранилище файловой системы из командной строки.
Для создания хранилища агента используется команда: storage create fs —storage name=“название хранилища”, path=“Путь на файловой системе” :
1zcli --config local.yml storage create fs --storage "name=fs-presigned, path=/mnt/fs/fs-presigned"
CLI может читать конфигурацию хранилища из стандартного ввода.
В Windows:
1 type s3_storage_conf.txt | zcli --config .auxdta/local.yml storage create s3
В Unix-подобных системах:
1 cat s3_storage_conf.txt | zcli --config .auxdta/local.yml storage create s3
Файл s3_storage_conf.txt можно создать в следующем виде (запятая в конце строки необязательна):
1 name=s3-presigned, 2 host=cloud.yandex.ru:8080, 3 ssl=true, 4 access_key=somekey, 5 secret_key=someotherkey, 6 provider=generic
Также можно ввести конфигурацию хранилища в интерактивном режиме. CLI запросит у вас все возможные параметры.
1zcli --config .auxdta/local.yml storage create s3
Удаление хранилища
Для удаления хранилища используется команда storage delete —name “название хранилища”:
1zcli --config local.yml storage delete --name s3-presigned
Получение списка всех доступных хранилищ
Используется команда storage list:
1zcli --config local.yml storage list 2zcli --c local.yml storage ls
Работа с Workspace
Создание workspace
Создание нового workspace с названием workspace-presigned:
1zcli --config local.yml workspace create --workspace "name=workspace-presigned, description=this is workspace presigned, defaultStorage=s3-presigned" 2zcli --config local.yml workspace create --workspace name=workspace-presigned, description=workspace-presigned-test, defaultStorage=s3-presigned 3cat wrkspc_cfg.txt | zcli --config local.yml workspace create
Обновление workspace
Обновление workspace workspace-presigned:
1zcli --config local.yml workspace update --name workspace-presigned --workspace name= new-name-workspace, description=new-description, defaultStorage=fs-presigned
Удаление workspace
1zcli --config local.yml workspace delete --name workspace-presigned
Получение списка workspace:
1zcli --config local.yml workspace list
Работа с Bucket
Создание нового бакета
Создание нового бакета в workspace:
1zcli --config local.yml bucket create --workspace workspace-presigned --bucket bucket-presigned
Удаление бакета без возможности восстановления:
1zcli --config local.yml bucket kill --workspace workspace-presigned --bucket bucket-presigned
Удаление бакета c дальнейшим переносом в корзину:
1zcli --config local.yml bucket delete --workspace workspace-presigned --bucket bucket-presigned
Получение списка всех созданных бакетов в workspace:
1zcli --config local.yml bucket list --workspace workspace-presigned
Получение статуса версионирования бакета:
1zcli --config local.yml bucket versioning get --workspace workspace-presigned --bucket bucket-presigned
Включение версионирования бакета:
1zcli --config local.yml bucket versioning put --workspace workspace-presigned --bucket bucket-presigned --versioning enabled
Отключение версионирования бакета:
1zcli --config local.yml bucket versioning put --workspace workspace-presigned --bucket bucket-presigned --versioning suspended 2Команды для работы с объектами:
Получить список объектов в бакете:
1 zcli --config local.yml object list --workspace workspace-presigned --bucket bucket-presigned 2 zcli -c local.yml o l --w workspace-presigned --b bucket-presigned
Получить версии указанного объекта:
1 zcli --config local.yml object list-versions --workspace workspace-presigned --bucket bucket-presigned --key-marker file1.txt 2 zcli -c local.yml o lv --w workspace-presigned --b bucket-presigned --k file1.txt
Загрузка файла в бакет:
1zcli --config local.yml object put --workspace workspace-presigned --bucket bucket-presigned --object-key file1.txt --file-name /home/doc/file.txt 2zcli -c local.yml o p --w workspace-presigned --b bucket-presigned --k file1.txt --f /home/doc/file.txt
Скачивание файла из бакета:
1zcli --config local.yml object get --workspace workspace-presigned --bucket bucket-presigned --object-key file1.txt -file-name /home/doc/new_file1.txt 2zcli -c local.yml o g --w workspace-presigned --b bucket-presigned --k file1.txt -f /home/doc/new_file1.txt
Удаление файла из бакета:
1 zcli --config local.yml object list --workspace workspace-presigned --bucket bucket-presigned --object-key file1.txt 2 zcli -c local.yml o l --w workspace-presigned --b bucket-presigned --k file1.txt
Добавление тегов к объекту:
1zcli --config local.yml object tags put --workspace workspace-presigned --bucket bucket-presigned --object-key file1.txt --version-id 21AB8121297712F --tags "key1 = val1, key2 =val2 " 2zcli -c local.yml o t p --w workspace-presigned --b bucket-presigned --k file1.txt --v 21AB8121297712F --t key1=val1,key2=val2 3cat tags.txt | zcli -c local.yml o t p --w workspace-presigned --b bucket-presigned --k file1.txt --v 21AB8121297712F
Получение тегов объекта:
1zcli --config local.yml object tags get --workspace workspace-presigned --bucket bucket-presigned --object-key file1.txt --version-id 21AB8121297712F 2zcli -c local.yml o t g --w workspace-presigned --b bucket-presigned --k file1.txt --v 21AB8121297712F
Удаление тегов объекта:
1zcli --config local.yml object tags delete --workspace workspace-presigned --bucket bucket-presigned --object-key file1.txt --version-id 21AB8121297712F 2zcli -c local.yml o t d --w workspace-presigned --b bucket-presigned --k file1.txt --v 21AB8121297712F
Создание мультипарт загрузки:
Команда на создание мультипарт загрузки: multipart-upload create —workspace “Название workspace” —bucket “Название бакета” —object-key “Название создаваемого файла в бакете”
1zcli multipart-upload create --workspace workspace-presigned --bucket bucket-presigned --object-key test1.txt
Загрузка части мультипарта: multipart-upload upload-part —workspace “Название workspace” —bucket “Название бакета” —object-key “Название создаваемого файла в бакете” —upload-id “upload-ID” —part-number номер —f “Путь к части файла”
1zcli multipart-upload upload-part --workspace workspace-presigned --bucket bucket-presigned --object-key test1.txt --upload-id d02b4050-3727-4da7-abff-4a30122209b9 --part-number 1 --f C:\Users\User\Desktop\test.txt
Завершение загрузки мультипарта: multipart-upload complete —workspace “Название workspace” —bucket “Название бакета” —object-key “Название создаваемого файла в бакете” —upload-id “upload-ID”:
1zcli multipart-upload complete --workspace workspace-presigned --bucket bucket-presigned --object-key test1.txt --upload-id d02b4050-3727-4da7-abff-4a30122209b9
Отмена загрузки мультипарта: multipart-upload abort —workspace “Название workspace” —bucket “Название бакета” —object-key “Название создаваемого файла в бакете” —upload-id “upload-ID”:
1zcli multipart-upload abort --workspace workspace-presigned --bucket bucket-presigned --object-key test1.txt --upload-id a42270b4-b5fb-4692-bc37-744506eac7b8
Получение списка частей мультипарт объектов: multipart-upload list-parts —workspace “Название workspace” —bucket “Название бакета” —object-key “Название создаваемого файла в бакете” —upload-id “upload-ID”
1zcli multipart-upload list-parts --workspace workspace-presigned --bucket bucket-presigned --object-key test2.txt --upload-id 7251085d-36da-4cbe-b470-ef8b693b4bed
Получить список мультипарт загрузок: multipart-upload list-uploads —workspace “Название workspace” —bucket “Название бакета”
1zcli multipart-upload list-uploads --workspace workspace-presigned --bucket bucket-presigned
Presigned URLs
Команда если нет файла конфигурации CLI (zakroma-config.yaml) или environment set:
1zcli --server.proto http --server.host yandex.ru --server.port 8081 --user Admin --password Password presign upload --f test_cli.txt --l 600 (Создать ссылку доступная 600 секунд на загрузку файла test_cli.txt)
Если есть файл конфигурации:
Загрузка файла
1zcli p u --f test_cli.txt --l 600 --t 2023-11-10T21:21:00 (Создать ссылку доступная 600 секунд и можно загружать файл после 2023-11-10 21:21:00 по локальному времени) 2zcli presign upload --f test_cli.txt --l 600 --t 2023-11-10T21:21:00
Для загрузки анонимному пользователю надо по полученной ссылке url надо отправить PUT-запрос и в теле запроса передать файл, в заголовке корректный Content-Length.
Скачивание файла
1zcli p g --k test_cli.txt --l 86400 (Создать ссылку на скачивание объекта доступная 24 часа с момента создания) 2zcli presign download --k test_cli.txt --l 86400
Удаление файла
1zcli p d --k test_cli.txt --t "2023-11-12 21:21:00Z" --l 600 (Создать ссылку на удаление файла доступная 10 минут 12 Ноября 2023 года после 00:00:00 UTC) 2zcli p delete --k test_cli.txt --t "2023-11-12 21:21:00Z" --l 600
Параметры команд
Все команды имеют как полную, так и сокращенную форму:
1подкоманды: 2 workspace, wsp, w 3 bucket, bck, b 4 storage, stg, s 5 object, obj, oРазвернуть
Примеры
Работа с хранилищами
Создание хранилища типа S3
1zcli --config local.yml storage create s3 --storage "name=st0002, host=cloud.yandex.ru:8080, region=Moscow, access_key=somekey, secret_key=someotherkey,ssl=yes,provider=generic" 2 или 3zcli -c local.yml stg crt s3 --s "name=st0002, host=cloud.yandex.ru:8080, region=Moscow, access_key=somekey, secret_key=someotherkey,ssl=yes,provider=generic" 4 или 5zcli -c local.yml s c s3 --s "name=st0002, host=cloud.yandex.ru:8080, region=Moscow, access_key=somekey, secret_key=someotherkey,ssl=yes,provider=generic"
Создание хранилища типа ZDS
1zcli --config local.yml storage create agent --storage "name=st0002, host=agent.digital-spirit.ru, port=8080, path=c:/mnt, access_key=somekey1, secret_key=someotherkey,ssl=yes"
Создание хранилища типа FS
1zcli --config local.yml storage create fs --storage "name=st0002, path=c:/mnt"
Удалить хранилище с именем st0002
1zcli --config local.yml storage delete --name st0002
Вывести список хранилищ
1zcli --config local.yml storage list 2 или 3zcli --c local.yml stg ls 4 или 5zcli --c local.yml s l
Работа с рабочими областями (Workspace)
1zcli --config local.yml workspace create --workspace "name=wrkspc4, description=space4, defaultStorage=st0002" 2zcli --config local.yml workspace create --workspace name=wrkspc4,description=space4,defaultStorage=st0002 3cat wrkspc_cfg.txt | zcli --config local.yml workspace create 4zcli --config local.yml workspace update --name wrkspc4 --workspace name=wrkspc04,description=space04,defaultStorage=st0002 5zcli --config local.yml workspace delete --name wrkspc4 6zcli --config local.yml workspace list 7 или, например, сокращенная версия команды: 8zcli -c local.yml wsp upd --n wrkspc4 --w name=wrkspc04,description=space04,defaultStorage=st0002 9 или 10zcli -c local.yml w u --n wrkspc4 --w name=wrkspc04,description=space04,defaultStorage=st0002
Работа с бакетами (Bucket)
1zcli --config local.yml bucket create --workspace wrkspc1 --bucket bck1 2zcli --config local.yml bucket update --workspace wrkspc1 --bucket bck1 --new-name bucket1 3zcli --config local.yml bucket delete --workspace wrkspc1 --bucket bck1 4zcli --config local.yml bucket list --workspace wrkspc1 5 или, например, сокращенная версия команды: 6zcli -c local.yml bck upd --w wrkspc1 --b bck1 --n bucket1 7 или 8zcli -c local.yml b u --w wrkspc1 --b bck1 --n bucket1
Управление версионностью Bucket
1zcli --config local.yml bucket versioning get --workspace wrkspc1 --bucket bck1 2zcli --config local.yml bucket versioning put --workspace wrkspc1 --bucket bck1 --versioning enabled ('on' instead of 'enabled' is possible) 3zcli --config local.yml bucket versioning put --workspace wrkspc1 --bucket bck1 --versioning suspended ('off' instead of 'suspended' is possible) 4 или, например, сокращенная версия команды: 5zcli -c local.yml bck vrs put --w wrkspc1 --b bck1 --v off 6 или 7zcli -c local.yml b v p --w wrkspc1 --b bck1 --v off
Работа с объектами
1Получить список объектов: 2 zcli --config local.yml object list --workspace wrkspc1 --bucket bucket1 --start-after file1.txt 3 zcli -c local.yml o l --w wrkspc1 --b bucket1 --s file1.txt 4Получить список версий: 5 zcli --config local.yml object list-versions --workspace wrkspc1 --bucket bucket1 --key-marker file1.txt 6 zcli -c local.yml o lv --w wrkspc1 --b bucket1 --k file1.txt 7Загрузить файл /home/doc/file.txt как объект file1.txt: 8 zcli --config local.yml object put --workspace wrkspc1 --bucket bucket1 --object-key file1.txt --file-name /home/doc/file.txt 9 zcli -c local.yml o p --w wrkspc1 --b bucket1 --k file1.txt --f /home/doc/file.txt 10Скачать объект file1.txt поместить его в /home/doc/new_file1.txt: 11 zcli --config local.yml object get --workspace wrkspc1 --bucket bucket1 --object-key file1.txt --file-name /home/doc/new_file1.txt 12 zcli -c local.yml o g --w wrkspc1 --b bucket1 --k file1.txt --f /home/doc/new_file1.txt
При скачивании без использования опции —file-name содержимое объекта будет помещено в текущую директорию под именем объекта.
Работа с тэгами объектов
1Добавить тэги: 2 zcli --config local.yml object tags put --workspace wrkspc1 --bucket bucket1 --object-key file1.txt --version-id 21AB8121297712F --tags "key1 = val1, key2 =val2 " 3 zcli -c local.yml o t p --w wrkspc1 --b bucket1 --k file1.txt --v 21AB8121297712F --t key1=val1,key2=val2 4 cat tags.txt | zcli -c local.yml o t p --w wrkspc1 --b bucket1 --k file1.txt --v 21AB8121297712F 5Получить тэги: 6 zcli --config local.yml object tags get --workspace wrkspc1 --bucket bucket1 --object-key file1.txt --version-id 21AB8121297712F 7 zcli -c local.yml o t g --w wrkspc1 --b bucket1 --k file1.txt --v 21AB8121297712F 8Удалить тэги: 9 zcli --config local.yml object tags delete --workspace wrkspc1 --bucket bucket1 --object-key file1.txt --version-id 21AB8121297712F 10 zcli -c local.yml o t d --w wrkspc1 --b bucket1 --k file1.txt --v 21AB8121297712F
Multipart upload
CLI выполнит Multipart upload автоматически, если загружаемый файл окажется больше 5 Гигабайт (5 368 709 120 байт), разделив файл на части по 8 Мб. Размер последней часть будет равен остатку от деления размера файла на 8 Мб. С помошью параметра —part-size(—s) можно задать желаемый размер части, однако, надо иметь ввиду, что он не может быть меньше 5 Мб и больше 5 Гб. Кроме того, если количество частей при заданном part-size превысит 10000, CLI автоматически увеличит размер части так, чтобы количество частей не превышало 10000. Если в процессе автоматической multipart-загрузки произойдет ошибка, можно попробовать продолжить загрузку, заново запустив команду с дополнительным параметром —start-from-part(—p), указав номер части, загрузка которой прервалась из-за ошибки.
Даже если размер загружаемого файла не превышает 5 Гб, и задан параметр —part-size, CLI выполнит multipart upload.
Также возможна загрузка нескольких файлов, как единого объекта с помощью команд Create multipart upload + UploadoObject part + Complete multipart upload. Части, загружаемые с помощью команды Upload object part, можно загружать в любом порядке, но объект будет собран в порядке возрастания номеров частей. При необходимости можно отказаться от создания объекта, инициированного командой Create multipart upload, и очистить хранилище от уже загруженных частей объекта с помощью команды Abort multipart upload. Например:
1Инициировать загрузку - Create multipart upload: 2 zcli -c local.yml m cr --w wrkspc1 --b bucket1 --k file1.txt --f /home/doc/file.txt 3Загрузить части - Upload parts: 4 zcli -c local.yml m u --w wrkspc1 --b bucket1 --k file1.txt --i cf333a14-01e5-4ed1-bbd8-4af105823591 --n 1 --f /home/doc/file1.txt 5 ... 6 zcli -c local.yml m u --w wrkspc1 --b bucket1 --k file1.txt --i cf333a14-01e5-4ed1-bbd8-4af105823591 --n 15 --f /home/doc/file15.txt 7Завершить и создать объект - Complete multipart upload: 8 zcli -c local.yml m cm --w wrkspc1 --b bucket1 --k file1.txt --i cf333a14-01e5-4ed1-bbd8-4af105823591 9Или прекратить/уничтожить загрузку и очистить память хранилища от уже загруженных частей - Abort multipart upload: 10 zcli -c local.yml m a --w wrkspc1 --b bucket1 --k file1.txt --i cf333a14-01e5-4ed1-bbd8-4af105823591 11Получить список инициированных, но не завершенных и не уничтоженных загрузок: 12 zcli -c local.yml m lu --w wrkspc1 --b bucket1 13Есть команда получения списка уже загруженных частей объекта, однако, она пока не работает: 14 zcli -c local.yml m lp --w wrkspc1 --b bucket1 --k file1.txt --i cf333a14-01e5-4ed1-bbd8-4af105823591
Presigned URLs
1Если конфигурация не задана ни в файле, ни в переменных окружения: 2 zcli --server.proto http --server.host zakroma-cloud.acme.com --server.port 8081 --user admin --password passwd --secret_key secrkey p u --f test_cli.txt --l 600 3--secret_key, впрочем, писать необязательно, так как команда может взять его с сервера. 4Если задана конфигурация: 5URL для загрузки объекта действительный в течение 10 минут, начиная с 11 ноября 2023 с 21:21:00 местного времени: 6 zcli p u --f test_cli.txt --l 600 --t 2023-11-10T21:21:00 7 zcli presign upload --f test_cli.txt --l 600 --t 2023-11-10T21:21:00 8URL для скачивания объекта, действительный в течение 24 часов начиная с момнета исполнения команды: 9 zcli p g --k test_cli.txt --l 86400 10 zcli presign download --object-key test_cli.txt --l 86400 11URL для удаления объекта действительный в течение 10 минут, начиная с 12 ноября 2023 с 00:00:00 по Гринвичу: 12 zcli p d --k test_cli.txt --t "2023-11-12 21:21:00Z" --l 600 13 zcli presign delete --object-key test_cli.txt --t "2023-11-12 21:21:00Z" --l 600 14URL для инициации multipart загрузки объекта: 15 zcli p cr --k test_cli.txt --t "2023-11-12 21:21:00Z" --l 600 16 zcli presign create-multipart-upload --k test_cli.txt --t "2023-11-12 21:21:00Z" --l 600 17URL для нормального завершения multipart загрузки и соборки объекта из частей: 18 zcli p cm --k test_cli.txt --t "2023-11-12 21:21:00Z" --i cf333a14-01e5-4ed1-bbd8-4af105823591 --l 600 19 zcli presign complete-multipart-upload --k test_cli.txt --upload-id cf333a14-01e5-4ed1-bbd8-4af105823591 --t "2023-11-12 21:21:00Z" --l 600 20URL для отказа от multipart загрузки объекта и очистки памяти в хранилище от уже загруженных частей: 21 zcli p ab --k test_cli.txt --i cf333a14-01e5-4ed1-bbd8-4af105823591 --t "2023-11-12 21:21:00Z" --l 600 22 zcli p abort-multipart-upload --object-key test_cli.txt --upload-id cf333a14-01e5-4ed1-bbd8-4af105823591 --t "2023-11-12 21:21:00Z" --l 600
Для пользователей ОС Windows.Флаг командной строки —escape-win/—ew/-e заменяет в сгенерированном URL символ % на %%, а символ & на ^&, что позволяет использовать получившийся URL в интерпретаторе комманд CMD.EXE непосредственно, например следующие 3 комманды делают:
- создаёт в текущей директории файл getfile.bat и записывает в него слово ‘curl ‘;
- дописывет в файл сгенерированный URL;
- исполняет getfile.bat, что приводит к скачиванию объекта test_cli.txt.
1< nul (set /p s=curl ) > getfile.bat 2zcli p g --k test_cli.txt --l 6000 -e >> getfile.bat 3.\getfile.bat