Runtime API
61 операция собственного runtime API SterBase: подключение named pipe, контекст сеанса, формы, данные, результаты и восстановление.
Runtime API — собственный локальный интерфейс работающего Enterprise SterBase. Он работает с текущим пользователем, базой и открытыми объектами через named pipe. Это самостоятельный runtime SterBase; нативная платформа 1С для выполнения этих операций не используется.
Каталог включает 61 операцию. Перед работой проверьте session_describe, доступные возможности сеанса и актуальный контекст. Внешний MCP-адаптер вызывает этот же API, а C ABI и C++ SDK служат для интеграции на другом уровне.
Полный каталог операций runtime API
| Операция runtime API | Назначение | Стандартный внешний MCP |
|---|---|---|
session_describe | Текущая база, пользователь, права, готовность и поддерживаемые операции. | sterbase_session_describe |
reference_get | Чтение по устойчивому адресу ContextReference; константы, планы и счета, документы и справочники. Текущая база и права проверяются заново. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
system_parameters_get | Рабочая дата, режим блокировки справочников/констант и ревизия системных параметров. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
system_parameters_set | Изменение поддерживаемого параметра working_date или lock_catalogs_and_constants с expected_revision. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
form_context_actions | Контекстные команды доступного элемента формы; результат содержит опубликованные токены действий. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
form_context_invoke | Выполнение контекстного действия через тот же обработчик, что используется приложением. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
constants_open | Открытие журнала констант с текущими правами и значениями на рабочую дату. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
periodic_history_open | Открытие истории периодического реквизита по объекту/полю либо принадлежащей API карточке. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
periodic_manage | Штатная команда периодических реквизитов для открытой формы; при необходимости возвращает выбор реквизита. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
tabular_rows | Чтение страницы строк табличного редактора, до 200 строк, с актуальной ревизией. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
tabular_select | Выбор строки табличного редактора. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
tabular_date | Дата представления периодических значений. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
tabular_edit | Начало редактирования выбранной строки. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
tabular_new | Черновик новой строки периодической истории. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
tabular_set | Задание скалярного значения/даты или типизированной ссылки черновика. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
tabular_save | Сохранение через общий обработчик с committed и readback_confirmed. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
tabular_choose | Типизированный подбор значения с продолжением selection_get/selection_choose. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
tabular_clear | Очистка значения текущего черновика. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
tabular_cancel | Отмена несохранённого изменения. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
tabular_delete | Удаление разрешённой записи истории через её штатный жизненный цикл. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
tabular_history | История выбранной константы или реквизита. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
tabular_refresh | Обновление представления без повторной записи. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
period_dialog_get | Чтение принадлежащего операции календарного диалога без его подтверждения. | sterbase_period_dialog_get |
period_dialog_complete | Применение или отмена периода через штатный обработчик диалога. | sterbase_period_dialog_complete |
list_period_set | Изменение периода своего журнала с сохранением фильтров и порядка. | sterbase_list_period_set |
accounting_totals_recalculate | Штатный пересчёт итогов с подтверждением, правом обслуживания и фактическим монопольным доступом. | sterbase_accounting_totals_recalculate |
marked_delete_open | Открытие штатного удаления помеченных объектов; список выбора изначально пуст. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
marked_delete_select | Явный выбор объектов в принадлежащем API сеансе удаления. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
marked_delete_check | Проверка ссылок и допустимости удаления выбранных объектов. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
marked_delete_execute | Подтверждённое удаление выбранного набора с проверкой ревизии и текущих прав; результат проверяется по объектам. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
marked_delete_close | Закрытие принадлежащего API сеанса удаления. | Прямой runtime API; отдельный инструмент стандартного адаптера не опубликован. |
selection_get | Чтение ожидающего типизированного выбора, включая печатную форму; операция ничего не выбирает. | sterbase_selection_get |
selection_choose | Продолжение опубликованного выбора: index начинается с нуля, -1 отменяет. | sterbase_selection_choose |
forms_list | Реальные открытые формы без передачи владения пользовательскими окнами. | sterbase_forms_list |
form_views | Вкладки и табличные области с ревизией и токенами навигации. | sterbase_form_views |
form_view_set | Переход к вкладке или строке через обычный обработчик, без записи и проведения. | sterbase_form_view_set |
metadata_list | Постраничный список читаемых метаданных. | sterbase_metadata_list |
metadata_get | Поля метаданных, типы, длины, точность и допустимые ссылочные цели. | sterbase_metadata_get |
object_list | Чтение справочников и документов без открытия формы. | sterbase_object_list |
object_get | Чтение точного объекта и его полей/строк по выданному токену. | sterbase_object_get |
list_open | Открытие списка или бухгалтерского журнала, при необходимости с периодом. | sterbase_list_open |
form_get | Семантическое состояние своей формы; закрытый токен не переадресуется другому окну. | sterbase_form_get |
list_select | Выбор точного объекта и выполнение обработчиков позиционирования. | sterbase_list_select |
list_activate | Активация объекта с учётом перенаправления формы или штатной отмены. | sterbase_list_activate |
form_snapshot | PNG-снимок готовой собственной формы вместе с её состоянием. | sterbase_form_snapshot |
form_close | Штатное закрытие собственной формы с уважением отказа обработчика. | sterbase_form_close |
session_close | Закрытие только принадлежащих API форм в обратном порядке. | sterbase_session_close |
session_shutdown | Завершение форм и явно назначенного собственного сеанса. | sterbase_session_shutdown |
operation_get | Опрос запущенной операции без повторения побочных эффектов; показывает доступные дочерние формы. | sterbase_operation_get |
form_set | Изменение опубликованных полей через обычные обработчики; не подтверждает запись. | sterbase_form_set |
form_actions | Доступные действия формы с одноразовыми токенами и ревизией. | sterbase_form_actions |
form_invoke | Выполнение опубликованного действия через обычный обработчик команды. | sterbase_form_invoke |
form_open | Открытие отчёта или обработки по точным метаданным. | sterbase_form_open |
object_draft_create | Черновик справочника или документа в памяти. | sterbase_object_draft_create |
object_draft_apply | Типизированные поля и полный набор строк версии черновика. | sterbase_object_draft_apply |
reference_select | Постраничный подбор типизированной ссылки с ограничениями поля. | sterbase_reference_select |
object_create | Фиксация подготовленного черновика через штатную запись; повтор того же черновика сверяет прежний результат. | sterbase_object_create |
object_save | Запись полей существующего объекта с контролем версии и состояния commit. | sterbase_object_save |
object_set_delete_mark | Установка или снятие пометки удаления по текущим правам. | sterbase_object_set_delete_mark |
document_set_posted | Проведение или отмена через общий жизненный цикл; открытая карточка требует владения и ревизии. | sterbase_document_set_posted |
accounting_total | Чтение бухгалтерского показателя за период по счёту. | sterbase_accounting_total |
Подключение и первый запрос
Работающий Enterprise публикует локальный endpoint SterBase-api-<PID>; имя можно задать переменной STERBASE_API_PIPE. Доступен только текущий пользователь Windows, сетевые клиенты pipe отклоняются. Python-клиент использует Python 3 и pywin32; после подключения сначала проверяйте session_describe.
from sterbase_api_client import Client
api = Client("SterBase-api-<PID>")
try:
session = api.call("session_describe")
if session.get("ok") and session.get("state") == "ready":
page = api.call("metadata_list", object_kind="catalog", limit=50)
finally:
api.close()Это пример чтения. Идентификаторы метаданных, токены и ревизии берутся из ответа текущего сеанса, а не угадываются. Для следующей страницы используется возвращённый cursor. Операции с данными выполняются под правами пользователя базы.
Результат, ожидание и восстановление
Изменяющий вызов отправляют один раз. Если получен operation_token, последующие запросы идут в operation_get; повтор открытия, записи или проведения не является опросом. operation_state описывает завершение команды, state — в том числе готовность результирующей формы. При pending требуется ожидать, а при interaction_required — обработать опубликованный выбор или дочернюю форму.
Перед изменением проверяются владение формой, тип токена и expected_revision. version_token относится к версии объекта, form_revision — к форме. form_set меняет поля и вызывает их обработчики, но сам по себе не подтверждает запись. Изменения нескольких полей могут быть частичными; проверяйте applied_count.
Фактическое сохранение определяется committed и контрольным чтением. reconciliation_required либо неизвестный исход требуют сверки до нового изменения. Внешний API не обещает долговечный exactly-once журнал после перезапуска. Устойчивый ContextReference сохраняет адрес для чтения, но не старые разрешения или временные токены.
Общие поля запроса и ограничения
| Поле / предел | Контракт |
|---|---|
operation | Строковое поле wire API; используется только поддерживающей его операцией. |
form_token | Строковое поле wire API; используется только поддерживающей его операцией. |
object_kind | Строковое поле wire API; используется только поддерживающей его операцией. |
metadata_id | Строковое поле wire API; используется только поддерживающей его операцией. |
object_token | Строковое поле wire API; используется только поддерживающей его операцией. |
cursor | Строковое поле wire API; используется только поддерживающей его операцией. |
limit | Строковое поле wire API; используется только поддерживающей его операцией. |
action_token | Строковое поле wire API; используется только поддерживающей его операцией. |
expected_revision | Строковое поле wire API; используется только поддерживающей его операцией. |
operation_token | Строковое поле wire API; используется только поддерживающей его операцией. |
draft_token | Строковое поле wire API; используется только поддерживающей его операцией. |
version_token | Строковое поле wire API; используется только поддерживающей его операцией. |
field_token | Строковое поле wire API; используется только поддерживающей его операцией. |
query | Строковое поле wire API; используется только поддерживающей его операцией. |
flag | Строковое поле wire API; используется только поддерживающей его операцией. |
period_from | Строковое поле wire API; используется только поддерживающей его операцией. |
period_to | Строковое поле wire API; используется только поддерживающей его операцией. |
account_code | Строковое поле wire API; используется только поддерживающей его операцией. |
metric | Строковое поле wire API; используется только поддерживающей его операцией. |
Wire v1: little-endian uint32 длины, UTF-8 поля, changes и rows. Запрос до 65 536 байт, ответ до 16 MiB. Даты — ISO YYYY-MM-DD в соответствующих полях; Python-клиент преобразует допустимые скалярные значения в wire-представление. Точные типы и required поля стандартного MCP ниже заданы JSON Schema.
reference_get читает catalog/document/constant/chart/account. Для периодической константы требуется явная дата; при готовом reference_path в query не смешивают новые селекторы. Табличный редактор требует актуальную ревизию; записи истории, созданные документом, доступны для просмотра, а не произвольной ручной перезаписи.