Console API и сборки
Console API v2, формат файла сборки и особенности работы сервера 1С:Элемента.
На странице описаны Console API, формат файла сборки и особенности работы сервера 1С:Элемента, выявленные при разработке elemctl. Эти сведения предназначены для разработчиков собственных клиентов и для анализа поведения сервера.
Контракт Console API v2
Общий префикс: {base}/console/api/v2. Тела запросов и ответов – JSON, кроме
загрузки сборки. Имена полей пишутся в kebab-case.
В справочнике консоли основной версией указана Console API 2.1 с префиксом
{base}/console/api/v2.1. Версия 2.0 также доступна. По умолчанию elemctl
использует 2.0, а к 2.1 обращается для работы с примененными расширениями,
которые в 2.0 недоступны.
При обращении к неподдерживаемому методу консоль возвращает 401 с текстом
Handler of HTTP request "[<метод>] <путь>" in application "console" not found.
Обновление токена не изменяет результат. Поэтому elemctl проверяет текст ответа
до обновления токена и сообщает о неподдерживаемом методе, а не об ошибке входа.
Приложения
GET /applications- список. Query-параметрnameу метода есть, но Console API его игнорирует и возвращает полный список. Это проверено живым вызовом, поэтому по имени фильтрует клиент.GET /applications/{id}- карточка. Значимые поля ответа:id,status,uri(адрес работающего приложения),error(текст ошибки, если есть),technology-version,date-updated,display-name,publication-context,source(объект с информацией об источнике, содержит в т.ч.project-version- версию примененной сборки).POST /applications- создать. Тело:source- объект{"type": "repository"}плюс ровно один из ключей:project-version-id(id сборки-источника) либоimage-id(id проекта);display-name,publication-context- имя и путь публикации;development-mode- булево, создавать ли среду разработки;- необязательные
space-id,technology-version.
DELETE /applications/{id}- удалить.PUT /applications/{id}/status/start- запустить.PUT /applications/{id}/status/stop- остановить.POST /applications/{id}/actions/debug- данные для сессии отладки (ApplicationDebugInfo:{"debug-token": ..., "debug-address": ...}). Тело запроса пустое; требует включенной отладки на сервере (config/debug.ymlenabled: true).POST /applications/{id}/project/update- применить сборку к приложению. Тело:{"source": {"type": "repository", "image-id": "<id сборки>"}}либо{"source": {"type": "repository", "project-id": "<id>", "assembly-version": "<версия>"}}(assembly-version необязательна). Сборку расширения принимает тот же метод и применяет рядом со сборкой приложения:source.project-version-idкарточки по-прежнему называет сборку приложения, а расширение появляется вextension-projectsметодаGET /v2.1/applications/{id}/project, с версией сборки вassembly-version.elemctlпроверяет такое применение по этому перечню.POST /applications/{id}/project/export– сборка, на которой работает приложение; справочник описывает метод и в 2.0, и в 2.1. Тело запроса пустое, ответ – сам архив,application/octet-streamбезContent-Disposition, с файлами сборки, упакованными заново. Консоль берет его у сервера приложения, и расширений, примененных в приложении, в нем нет. Во время обновления и после неудачного обновления ответом приходит сборка, загруженная для этого обновления. Сборка, загруженная в проект, возвращается с номером, который дал ей сервер, в манифесте. Обработчик 2.1 принимает и недокументированный параметр запросаextension-idи тогда отвечает сборкой этого расширения.elemctl apps exportзаписывает архив под именем{Имя} {Версия}.xasm.POST /applications/{id}/dumps- создать дамп. Тело:include-users,include-binary-data(булевы),description(строка).GET /applications/{id}/dumps/{dumpId}- статус дампа.GET /applications/{id}/users– пользователи, подключенные к приложению, каждый{user-list-id, user-id, presentation, is-admin, token-access-enabled}. Среди них и пользователи панели управления: их сервер подключает сам и называет такого пользователя по логину.token-access-enabled– доступ пользователя к HTTP-сервисам приложения по токену; без него вызов сервиса токеном этого пользователя получает 500 “Token access is denied”.PUT /applications/{id}/users/change-token-access– переключить этот доступ. Тело:{"user-list-id", "user-id", "enable-access"}, все три обязательны; ответ – подключение в том виде, в каком оно стало. Пользователь, не подключенный к приложению, получает 500 “Can’t change user token access” без объяснения причины. Метод описан и в v2, и в v2.1.elemctl apps token-accessсначала находит подключение, а после переключения перечитывает признак; весь перечень печатаетelemctl apps users.GET /me– пользователь, которому принадлежат реквизиты:id,login,presentation,user-list-id.GET /v2.1/applications/{id}/project– проекты, которые работают в приложении:application-projectи примененные расширения вextension-projects, у каждогоid,project-id,assembly-id,enabled,order,vendor-name,project-name,project-presentation,project-versionиassembly-version.id– ид расширения на сервере приложения:ИдизПроект.yamlрасширения, тотconfiguration-id, которым ответила его загрузка. Вassembly-idрасширения в ответе указывается ид его проекта. Это поле не содержит ид сборки. Тот же путь в 2.0 отвечает одним проектом приложения.POST /v2.1/applications/{id}/project/{ExtensionId}/export– сборка примененного расширения. Тела нет, ответ – сам архив,application/octet-streamбезContent-Disposition, в нем файлы, с которыми сборку загрузили. Сегмент пути –idрасширения, регистр букв не важен. Справочник называет параметр идентификатором проекта расширения, но наproject-idсервер отвечает тем же ответом 500 без пояснения “Unable to export extension … from application …”, что и на неизвестное значение. Остановленное приложение отдает сборку так же. В 2.0 такого метода нет.elemctl apps export-extensionсначала ищет расширение по любому из его имен и сохраняет архив под именем{Имя} {Версия}.xasm.
Статусы приложения делятся на две группы:
- стабильные:
Running,Stopped,Error; - переходные:
Starting,Stopping,Initializing,Updating,Frozen,Creating,Deleting.
Во время перехода поле status может быть пустым. Справочник определяет это поле
как строку без перечня значений; приведенный список составлен по результатам
проверок на стендах. Статус Deleting сохраняется во время задачи
DeleteApplication. После ее завершения запись остается в списке со статусом Deleted.
Статус UNKNOWN наблюдался у приложения с отсутствующими файлами базы. Запуск
и удаление были недоступны, поскольку удаление начинается с выгрузки данных.
Консоль использует UNKNOWN для состояния сервера приложения, которому
не сопоставлено имя статуса. Это не подтверждает окончательное состояние.
Клиент не относит его к стабильным или переходным: если UNKNOWN сохраняется
минуту подряд, ожидание прекращается с сообщением об этом статусе.
Версия технологии
- Чтение - из поля
technology-versionкарточки приложения (отдельный endpoint чтения есть не во всех версиях сервера - не использовать). - Обновление:
POST /tasks/group-tasks/update-applications-technology, тело{"technology-version": "<версия>", "applications": ["<app-id>"]}. Возвращает групповую задачу; ее статус -GET /tasks/group-tasks/{taskId}.
Пространства и проекты
GET /spaces- список пространств.GET /projects- список проектов;GET /projects/{id}- карточка;DELETE /projects/{id}- удаление. Вид проекта лежит вproject-kind:Application,LibraryилиExtension, аGroup- у группы проектов, которую список содержит наряду с ее участниками.
Сборки проекта (assemblies)
- Загрузка файла сборки - бинарный POST (Content-Type
application/octet-stream, тело - байты файла):POST /projects/{id}/assemblies- добавить сборку в существующий проект;POST /projects- создать новый проект из сборки либо добавить сборку в проект с темИд, что записан в ееПроект.yaml;POST /spaces/{space-id}/projects- то же, но новый проект заводится в этом пространстве.
Параметры загрузки
Пространство для загрузки в существующий проект задается необязательным
query-параметром space-id. При проверке сервер вернул 400 для значения, не
соответствующего UUID, и 404 для неизвестного пространства. Параметр SpaceId
в PascalCase игнорируется.
У POST /projects параметр пространства не описан и не обрабатывается ни в одном
написании: запрос с space-id=not-a-uuid создал проект. Для создания проекта
в определенном пространстве используется POST /spaces/{space-id}/projects.
Неизвестное пространство возвращает 404. Если проект с Ид сборки уже существует,
сборка добавляется в него, как при POST /projects.
Для POST /projects/{id}/assemblies коммит передается параметром commit-id
и сохраняется в карточке сборки. Проверка схемы следующего развертывания
сравнивает исходники с этим коммитом. Параметры branch-name, commit-message
и modified также описаны и принимаются сервером, но не выводятся в карточке.
branch-name означает ветку групповой разработки, а не git. Значение modified=1
возвращает 500. Параметры CommitId, BranchName и CommitMessage в PascalCase
игнорируются. Для POST /projects параметр коммита не описан; у сборки, создающей
проект, коммит в карточке отсутствует.
elemctl передает только коммит. Ветка, признак незакоммиченных изменений и каталог исходников записываются в локальный реестр загрузок.
Нумерация загруженных сборок
POST /projects/{id}/assemblies не использует версию архива. Базовая версия
читается из Версия описания проекта. Номер сборки равен наибольшему когда-либо
выданному номеру этой базовой версии плюс один. В проверках получены такие результаты:
| Версия архива | Версия после загрузки |
|---|---|
1.0.0-i1 |
1.0.0-1 |
1.0.0-10001 |
1.0.0-2 |
1.0.0-2, уже существующая в проекте |
1.0.0-3 |
1.0.1-7, при 1.0.0 в описании проекта |
1.0.0-502 |
Удаление сборки не уменьшает счетчик. После удаления 1.0.0-4 с конца списка
следующей стала 1.0.0-5. После удаления 1.0.0-50 и 1.0.0-51 следующая
загрузка получила 1.0.0-52, хотя список заканчивался на 1.0.0-8. Удаление
сборки из середины списка также не изменяет счетчик. Сам счетчик через API
недоступен: в карточке проекта его нет, удаленные сборки не перечисляются,
а запрос карточки удаленной сборки возвращает 404. Назначенный номер доступен
в assembly-version ответа на загрузку.
Загрузка без ид проекта, POST /projects, сохраняет версию архива, включая
нечисловой суффикс. Если версия уже существует, возвращается 409. Номер удаленной
сборки можно использовать повторно, но счетчик проекта не уменьшается: после
повторной загрузки архива 1.0.0-2 следующая загрузка в проект получила
1.0.0-8, а не 1.0.0-3. Таким образом, суффикс с номером запуска CI сохраняется
при загрузке без ид проекта, но не при загрузке в проект по его ид.
Команда elemctl deploy до сборки предупреждает, если сервер изменит заданную
версию. После загрузки выводится фактически назначенная версия. Без явной версии
используется больший номер из списка сборок и локального реестра загрузок.
Реестр содержит номера сборок этой машины, включая впоследствии удаленные.
Если сборка была загружена с другой машины и удалена, ее номера может не быть
в обоих источниках. В таком случае сообщение после загрузки указывает,
что номер назначен сервером.
Проект в ответе на загрузку
Ид созданной сборки читается из image-id, assembly-id или id в этом порядке.
Объект artifact содержит сведения о проекте:
artifact-id– ид, по которому доступна карточка проекта;configuration-id–ИдизПроект.yaml;name– представление проекта.
В панели проект отображается под Представление последней загруженной сборки,
а не под Name из манифеста. Это подтверждено загрузками с одним Ид
и разными Name и представлениями. Сборка с другим именем переименовывает проект
без отдельного сообщения сервера; следующая сборка с прежним именем возвращает его.
Переименование затрагивает проект и его группу; удаление сборки не возвращает
прежнее имя. Если несовпадение известно до загрузки, builds upload отклоняет
операцию без --force-rename. Проверка вспомогательная: если манифест не читается
или карточка проекта недоступна, загрузка продолжается без сравнения имен.
Загрузка без ид проекта также может переименовать существующий проект. Сервер
выбирает его по Ид, а отдельного метода поиска по этому полю нет. Поэтому
builds upload читает список проектов до загрузки и сравнивает с ним artifact
ответа. В результате указывается выбранный проект, признак его создания
и предупреждение о переименовании.
-
Проект опознается по
ИдизПроект.yaml, возвращаемому вconfiguration-id. ПриPOST /projectsсначала ищется действующий проект с этимИдв пространстве загрузки, затем в остальных пространствах. Если он найден, сборка добавляется в него независимо от поставщика и имени в манифесте. Ид выбранного проекта возвращается вartifact-id.Пара
Vendor+Nameдолжна быть уникальна среди проектов пространства. В проверке сборкиacme/crm,acme/crm-nextиglobex/crmс однимИдвключались в один проект и изменяли его имя. Сборкаacme/crmс новымИдполучила 409.Ответ 409
ALREADY_EXISTSимеет две причины:- версия уже загружена: “Версия сборки … уже присутствует в группе проекта”;
- новый
Идиспользует занятую пару поставщика и имени: “Сборка с именем поставщика … уже зарегистрирована в другом проекте”. Начатое создание проекта с такимИдотменяется.
В исходниках консоли поиск по
ИдвыполняетFindProjectById. При проверке назначение сборок в существующий проект подтверждено также дляPOST /spaces/{space-id}/projects. Для отдельного временного проекта тех же исходников необходимы новыйИди новая пара поставщика и имени. -
GET /projects/{id}/assemblies- список сборок. Элемент содержитassembly-version, строку вида1.0-42, и id в полеidлибоimage-id. Ответ приходит массивом или объектом, у которого список лежит в полеitemsилиassemblies. Страниц у метода нет, и общего числа он не сообщает. Параметрыlimit,size,pageSize,count,top,maxResults,page,pageNumber,offset,skip,fromиstartметод игнорирует: ответ на все эти запросы совпадает побайтно, а ни в заголовках, ни в теле нет ни счетчика, ни курсора. Проверено живыми вызовами на двух установках. Консоль автоматически удаляет сборки, которыми никто не пользуется, независимо от возраста. Проверка выполняется, когда приложение заканчивает применение сборки. Фоновое задание обрабатывает сборки проекта этого приложения с той же базовой версией, что у примененной сборки. За одно применение удаляется не больше десяти сборок. Сохраняются:- релизные и защищенные сборки;
- сборка проекта по умолчанию;
- сборки работающих приложений и сборки, загруженные в приложения;
- сборка с наибольшим номером этой базовой версии.
Сборка, загруженная без ид проекта (
POST /projects), защищена с момента создания, как и сборка, из которой создан репозиторий проекта. Загрузка в проект по ид (POST /projects/{id}/assemblies) не устанавливает защиту. Библиотечная сборка без оставшихся зависимых сборок удаляется вместе со своей группой.Сборки проекта расширения автоматически не удаляются. Применение расширения запускает то же обновление, но последующая очистка проверяет проект и базовую версию приложения. Проект расширения сохраняет сборки до ручного удаления или удаления вместе с проектом.
Это подтверждено проверкой: приложение работало на
1.0.0-1, а в его проект по ид были загружены1.0.0-2и1.0.0-3. В проекте расширения находились сборки с1.0.0-1по1.0.0-4. Применение расширения1.0.0-2удалило1.0.0-2из проекта приложения и не удалило сборки расширения. Последующее применение1.0.0-4сохранило сборки расширения1.0.0-2и1.0.0-3.Проект, к приложениям которого сборки не применяются, сохраняет все сборки. Заранее загруженная сборка защищена номером только пока он наибольший. Отдельная проверка девяти сборок подтвердила исходники консоли из дистрибутива:
- создание приложения за две минуты наблюдения ничего не удалило;
- применение
1.0.0-3до возврата ответа удалило1.0.0-2,1.0.0-4и1.0.0-11; сохранились1.0.0-1и1.0.0-10, загруженные без ид проекта, примененная1.0.0-3, наибольшая1.0.0-12и обе сборки2.0.0; - применение
1.0.0-12удалило1.0.0-3; - применение
2.0.0-1ничего не удалило, включая1.0.0-12, поскольку очистка относилась только к базовой версии2.0.0.
Ранее из семнадцати сборок дневной серии осталась только примененная, а первая сборка проекта двухмесячной давности сохранилась: она была загружена без ид проекта. Клиент должен описывать ответ как перечень сохранившихся сборок, а не историю проекта или страницу истории.
-
GET /projects/{id}/assemblies/{version}- карточка сборки,DELETE .../{version}- удаление. Последний сегмент - это версия, как метод ее и называет:assembly-versionилиproject-version, строка вида1.0-42. Ид карточки сюда не подходит: на UUID метод отвечает 404 “Assembly with versionnot found”. Проверено живыми вызовами на двух установках разного возраста, ведут себя одинаково. При этом ид - тоже адрес, который есть на руках: его печатает перечень сборок и возвращает загрузка. Поэтому elemctlпринимает обе формы. Версия определяется по списку сборок. Если значения нет ни в одной карточке, возвращается сообщение об отсутствующей сборке, а если адрес отклонен с 400 или 404, пробует сегментом и ид - на случай установки, которой нужна эта форма. Версия сборки, загруженной в проект, – номер, который дал сервер, а не версия ее архива. Удаление сборки сервер отклоняет с 500, пока существует созданное из нее приложение. После его удаления тот же запрос выполняется успешно. Сборка, использованная только при применении, включая применение с последующим откатом, может быть удалена. Ответ 500 не означает ошибочный формат адреса: он возвращается вызывающей стороне без повторной попытки с другой формой адреса.
Версии сборок сравнивают по числовому суффиксу после последнего дефиса: 1.0-10
новее, чем 1.0-9. Лексикографическое сравнение дает неверный порядок.
Ветки среды разработки
GET /branches- список; необязательные queryproject-id,name.GET /branches/{id}- карточка. Поля:name,kind,project,application,source-branch,deletion-mark,version-stamp.POST /branches- создать. Тело:name,kind: "development",project: {"id": "<id>"}, необязательноapplication: {"id": "<id>"}.PUT /branches/{id}- изменить. Сервер использует оптимистическую блокировку, поэтому сначала прочитайте карточку, а затем отправьте тело, собранное из текущих значений. Этоname,kind,deletion-markиversion-stamp, который обязательно вернуть как есть. Поляsource-branchиapplicationсвернуть до{"id": ...}, а если ид нет, то до{"name": ...}. Чтобы перепривязать ветку к приложению, заменитеapplicationна{"id": "<новый app-id>"}.- Изменения ветки принимает тот же
PUT /branches/{id}с дополнительным ключом телаwrite-parameters: {"merge": true}. DELETE /branches/{id}- удалить ветку.
Инструмент работает только с документированным Console API v2. Внутренние, то есть недокументированные, API консоли управления он не использует и не описывает.
Списки пользователей
Список пользователей держит либо пользователей приложения, либо пользователей
панели управления. У приложения список свой и назван по нему, а карточка
приложения указывает на него полем default-user-list. У панели управления
список один на установку.
GET /user-lists- список:id,presentation,space-id. Фильтра по имени на сервере нет.GET /user-lists/{id}- полная карточка.POST /user-listsсоздает список и требует карточку целиком: на неполное тело он отвечает 500 с обманчивым текстом “Failed to parse json”.DELETE /user-lists/{id}удаляет.GET|PUT /user-lists/{id}/settings/self-registration-{enabled, phone-required, email-required}, это “Разрешить пользователям регистрироваться самостоятельно” из панели.GET|POST /user-lists/{id}/settings/account-services-settings,PUT|DELETE .../{account-service-id}- сервисы учетных записей. Запись:{account-service-id, account-service-type, local-id, enabled, create-user-on-auth, additional-settings}; типLocalаутентифицирует паролем, остальные (OIDC,Cas,ActiveDirectory,Esia) внешние. Обе записи требуют запись целиком.GET|POST|DELETE /applications/{id}/userlists- ид списков, подключенных к приложению. Обратите внимание на написание: здесьuserlists, а на верхнем уровнеuser-lists. Собственных настроек у связи нет.GET /user-lists/{id}/users– пользователи списка, среди полейidиlogin. Запись содержит токены доступа пользователя и секреты. Такой ответ нельзя записывать в журнал без удаления конфиденциальных полей.
Ограничения API списков пользователей:
- Если Console API v2 пропускает поле
calculation-rulesпри чтении сервиса учетных записей, меняйте правила в панели управления. PUT сuserPropertiesCalculationRulesможет вернуть успешный ответ, оставив правила пустыми. - состава форм аутентификации приложения в API нет, как и настройки подключения “пользователи списка подключаются автоматически при входе”. Это остается в панели;
- GET сервиса учетных записей отдает
client_secretOIDC-клиента открытым текстом, так что таким ответам не место в логах и отчетах как есть; - неизвестный путь Console API отвечает 401 с текстом “Handler of HTTP request … not found”, а не 404. Такой ответ означает, что запрошенный метод отсутствует.
Задачи приложений
GET /tasks/application-tasks - список задач всех приложений. Серверного фильтра
нет, фильтровать приходится на клиенте. Поля задачи: id, application-id,
status (в т.ч. Error, Failed), operation-type, error-message,
start-date (ISO 8601, может оканчиваться на Z).
Формат файла сборки (.xasm / .xlib)
Файл сборки - ZIP-архив (deflate):
-
в корне
Assembly.yaml- манифест, плоские пары ключ-значение:ManifestVersion: 1.0 | 1.1 ProjectKind: Application | Library | Extension Vendor: <поставщик> Name: <имя проекта> Version: <версия, например 1.0-42> Created: <UTC, формат YYYY.MM.DD HH:MM:SS> BranchName: <имя git-ветки> CommitId: <хэш коммита>Для библиотеки (
ProjectKind: Library) в конце добавляется строкаRelease:(пустое значение); расширение файла.xlib, для приложения и расширения –.xasm.Расширение (
ProjectKind: Extension) пишется сManifestVersion: 1.1, остальные виды – с1.0. Версия манифеста определяет способ его разбора сервером. Версия 1.0 поддерживает толькоApplicationиLibrary: применение расширения с манифестом 1.0 отклоняется с ошибкой “Неизвестный вид проекта: "Extension"”. Такая же пара значений используется в сборках расширений из консоли. -
далее файлы проекта путями
{vendor}/{name}/...- относительно корня репозитория. Каталог проекта обязан лежать по схеме{repo}/{vendor}/{name}/Проект.yaml. Разделители путей в архиве - прямые слэши (и на Windows).
Имя файла сборки: {Имя} {Version}.xasm (через пробел).
Метаданные проекта берутся из Проект.yaml. Это YAML, и достаточно разобрать
плоские пары “ключ: значение” верхнего уровня, а вложенные строки с отступом
пропустить. 1С:Элемент поддерживает двуязычные исходники, дескриптор с
английскими ключами применяется штатно, поэтому каждый ключ читается в обоих
написаниях: Имя/Name, Поставщик/Vendor, Версия/Version (базовая,
например 1.0) и ВидПроекта/ProjectKind. Значение Библиотека или
Library означает библиотеку, Расширение или Extension – расширение, все прочее –
приложение. Если встретились сразу
оба написания ключа, используется русское значение. Двуязычны и имена служебных файлов:
конвертер 1С:Элемента принимает Project.yaml и Проект.yaml, Subsystem.yaml
и Подсистема.yaml. У английского дескриптора английские и значения
перечислений, например VisibilityScope: Global.
Если версия сборки не задана явно, она собирается как {базовая версия}-{N+1},
где N - счетчик из версии последней сборки проекта той же базовой версии.
deploy берет за N больший из двух номеров: номер последней сборки в перечне и
наибольший номер проекта в локальном реестре загрузок для этой
базовой версии. Сервер считает от наибольшего номера, какой он когда-либо выдавал, считая
и удаленные сборки. Проект, поднятый на новую базовую версию, снова начинает с
-1, какие бы номера ни
набрала старая база. Когда последней сборки этой базы нет, суффикс берется из
номера запуска CI в окружении: первое числовое значение из CI_PIPELINE_IID,
GITHUB_RUN_NUMBER, BUILD_NUMBER, в указанном порядке. Иначе чистый рабочий
каталог CI давал бы -1 каждый раз. Нет и номера CI - остается
{базовая версия}-1.
Git-метаданные, то есть хэш коммита и имя ветки, берутся из git-репозитория, который содержит каталог проекта. Если git недоступен, поля остаются пустыми.
Отбор файлов в архив:
- включаются только расширения:
.yaml .xbsl .xbql .md .txt .json(исходники),.png .svg .jpg .jpeg .gif .webp .ico(изображения),.css .htm .html .js .woff .woff2 .ttf .eot(веб-ресурсы); - внутри каталога
Ресурсыотбор по расширению не действует, на любом уровне и в подкаталогах тоже: по документации 1С:Элемента ресурс - это произвольный файл, поэтому оттуда берется все; - файлы описания клиента SOAP-сервиса включаются, где бы они ни лежали:
<ИмяКлиента>.Wsdl.<n>и<ИмяКлиента>.Xsd. Файлы располагаются рядом с элементом проекта и читаются по имени; - исключаются каталоги
.git,.claude,.github,__pycache__,node_modules,.venvи все скрытые (начинающиеся с точки); - исключаются файлы
.gitignore,.env,.DS_Storeи файлы*.xasm,*.xlib.
Разбор готового архива
Операция, обратная сборке: по файлу .xasm или .xlib читаются манифест,
свойства проекта из его Проект.yaml внутри архива и состав. Она нужна, чтобы
подключить библиотеку к проекту, не разворачивая ее исходники.
Структура проекта определяется по каталогам:
- каталог первого уровня - это подсистема. Файл
Подсистема.yamlнеобязателен, у подсистемы библиотеки он может отсутствовать, поэтому при поиске подсистем на него опираться нельзя; - вложенный каталог подсистемы - это пакет. Файла-описания у пакета нет, и каждый каталог дает сегмент имени;
- полное имя типа:
{vendor}::{name}::{подсистема}[::{пакет}]::{ИмяТипа}. То же имя без последнего сегмента указывается вИспользованиеиимпорт.
Наружу, в подключивший проект, видны только типы с ОбластьВидимости: Глобально. По умолчанию стоит ВПодсистеме, а глобальная область пишется явно.
Совместимость проверяется по свойству РежимСовместимости файла Проект.yaml.
Свойства ВерсияТехнологии в Проект.yaml не существует: оно относится к
телу запроса Console API на создание приложения, а не к файлу проекта.
Особенности работы сервера
-
Откат без сообщения. При ошибке применения сборки, например ошибке компиляции, сервер восстанавливает предыдущую сборку и запускает приложение. Статус
Runningне подтверждает применение. Для проверки:- получить задачи приложения со статусом
ErrorилиFailed, у которыхstart-dateне раньше начала развертывания; - сравнить
source.project-versionкарточки приложения с загруженной сборкой; - для расширения проверить версию и
enabledвextension-projectsметодаGET /v2.1/applications/{id}/project. Карточка приложения содержит только сборку самого приложения. Без Console API 2.1 применение расширения остается непроверенным; это не подтверждает откат; - дополнительно выполнить GET по
uri. Для закрытых приложений ответы 401 и 403 допустимы.
- получить задачи приложения со статусом
-
Создание без данных проекта. При некоторых настройках сервера источник “проект”, то есть
image-idс ид проекта, создает пустое приложение. Для получения данных проекта указать конкретную сборку вproject-version-id, например последнюю сборку. -
Удаление с неопубликованными изменениями. Если в среде разработки есть такие изменения,
DELETE /applications/{id}возвращает 400FAILED_PRECONDITION. Принудительного удаления в API нет; используется панель управления. Клиент должен сообщить об этом ограничении. -
Готовность нового приложения. После создания приложение некоторое время находится в переходном статусе без
uri. Необходимо дождаться стабильного статуса и появленияuri. ПриErrorожидание прекращается с ошибкой. -
Перезапуск после применения.
project/updateможет перезапустить приложение. После вызова дождаться окончания переходного статуса. Если итог отличается отRunning, остановить приложение, если оно еще неStopped, дождатьсяStopped, затем запустить и дождатьсяRunning. Ориентиры ожидания: 3 минуты для остановки, 5 минут для запуска и стабилизации, опрос каждые 10 секунд. -
Окончательный статус
Error. При стабильномErrorвернуть ошибку и тексты задач приложения. Не следует перезапускать приложение или ожидать другого статуса: изErrorоно не переходит вStopped, и ожидание завершится только по предельному сроку. -
Windows. Для временных файлов и кешей использовать
tempfile. Для stdout и stderr установить UTF-8 черезreconfigure, чтобы сохранить кириллицу. -
Идентификация проекта. Проект опознается по
ИдизПроект.yaml. ПараVendor+Nameдолжна быть уникальна среди проектов пространства. Загрузка без ид проекта может добавить сборку в существующий проект с такимИд; создание нового проекта не гарантируется. -
Фоновое удаление.
DELETE /applications/{id}возвращает ответ до окончания задачиDeleteApplication. Пока приложение существует, удаление исходной сборки завершается 500. Сначала удалить приложение, дождаться 404 при запросе его карточки или статусаDeleted, затем удалить сборку. -
Серверная компиляция. Локальная сборка упаковывает архив. Проверки синтаксиса, типов и видимости выполняются серверным компилятором при применении сборки или создании приложения. Отдельного метода компиляции нет. Команда
elemctl probeзагружает исходники в их собственный проект с одноразовой версией, создает временное приложение для компиляции и удаляет оба объекта после проверки. Рабочее приложение не изменяется. -
Вход в новое приложение. У приложения собственный пустой список пользователей, указанный в
default-user-list. Вход по паролю выключен, сервис учетных записей отсутствует. Подключение списка другого приложения черезPOST /applications/{id}/userlistsи включение локального входа не обеспечивают вход учетными записями других приложений. Для входа используется учетная запись панели управления: ее пользователи подключаются сервером автоматически. Способ входа не виден из карточки; подбирать учетную запись не следует, поскольку учитываются неудачные попытки. -
Запуск сервера. После запуска или обновления консоль может быть недоступна несколько минут; после одного обновления ожидание составило тринадцать минут. Все запросы, включая получение токена, возвращают 404 с текстом
Application "console" not found. От отсутствующего приложения или сборки этот случай отличается текстом ответа. elemctl сообщает о запуске сервера; повторный запрос возможен после ответа 302 от/console. Командаdeployожидает до--server-start-timeoutсекунд, по умолчанию 900; значение 0 отключает ожидание. После доступности консоли выполнение продолжается. Повтор отклоненного запроса безопасен: консоль его не обработала. -
Удаление данных при изменении исходников. Удаление табличной части из исходников приводит к удалению ее строк при применении без предупреждения. Это проверено на справочнике с одной строкой в табличной части: задача завершилась успешно, приложение продолжило работу. Аналогично удаляются реквизиты табличных частей и объектов со значениями, а также весь справочник при отсутствии его описания; последнее проверено на пустом справочнике. Пересоздание описания под теми же путем и именем с новым
Идтакже удаляет данные: после проверки справочник с двумя строками оказался пустым при успешной задаче применения.Сужение длины и смена типа пересоздают данные объекта.
elemctl deployотклоняет эти изменения без явного разрешения, как и полное удаление справочника, документа или регистра. При удалении реквизита или табличной части команда до сборки перечисляет удаляемые данные и продолжает выполнение.