Справочник API БСП
Офлайн-справочник по программному интерфейсу БСП: 2624 метода в 284 модулях, 71 подсистема, версии 3.1.11 и 3.2.1. Собран из двух источников одновременно - структура и сигнатуры из документации, модули и экспортность из самой библиотеки. Каждая версия документации сведена со своим дистрибутивом, поэтому различия между версиями видны, а не усреднены.
Назначение написано нами: одна строка у каждого из 284 модулей и у 440 методов ядра. Описательный текст документации ИТС в справочник не переносится.
Справочник больше мегабайта, в контекст целиком не грузится. Он спрашивается по месту.
Главное правило
Не пиши вызов метода БСП, не проверив его. Имена в БСП длинные и составные, поэтому
правдоподобная выдумка выглядит как настоящее имя. Классические несуществующие:
ФайловаяСистемаКлиентСервер, JSONСтрокой, Пользователи.СсылкаТекущегоПользователя.
bashpython skills/1c-bsp-api/scripts/bsp-api.py check ФайловаяСистемаКлиентСервер.ПолучитьФайл
Код возврата 1, если вызова нет. При промахе инструмент подсказывает похожие имена - и по модулю, и по методу.
Как устроена библиотека
Суффикс имени модуля - это контекст выполнения, а не тематика. Один механизм разложен по нескольким модулям, и выбор между ними определяется тем, откуда идет вызов:
| Суффикс | Где исполняется | Пример |
|---|---|---|
без суффикса или Сервер | сервер, толстый клиент, внешнее соединение | ОбщегоНазначения |
Клиент | тонкий и толстый клиент | ОбщегоНазначенияКлиент |
КлиентСервер | и там, и там | ОбщегоНазначенияКлиентСервер |
ВызовСервера | сервер, вызывается с клиента напрямую | ОбщегоНазначенияВызовСервера |
Отсюда частая ошибка: серверный метод вызывают из клиентского кода. Контекст каждого метода есть
в справочнике, отбор - ключом --av (S сервер, T тонкий, F толстый, E внешнее
соединение, C вызов сервера).
Три вида модулей по назначению:
- Обычные - публичный интерфейс, их и вызывают:
ОбщегоНазначения,Пользователи,УправлениеПечатью. Переопределяемый- точки расширения. Их не вызывают, в них ПИШУТ: обработчик вызывает библиотека, а тело пишет внедряющая конфигурация. Таких методов 372.Служебный- внутренняя реализация библиотеки. В программный интерфейс не входит ни один служебный метод, и вызывать их нельзя: они меняются между версиями без объявления.
Еще два суффикса встречаются реже: ПовтИсп - модуль с повторным использованием возвращаемых
значений, Локализация - национальная специфика.
Часть интерфейса объявлена не в общих модулях. Обмен данными опубликован модулями объектов
обработок (Обработка.УниверсальныйОбменДаннымиXML, Обработка.КонвертацияОбъектовXDTO).
В справочнике они есть наравне с общими модулями.
Запросы
bashB=skills/1c-bsp-api/scripts/bsp-api.py python $B find печать # поиск по имени, модулю, подсистеме, назначению python $B find "реквизит объект" # ищутся все слова запроса сразу, не подстрока python $B find файл --av T # только то, что доступно на тонком клиенте python $B show ОбщегоНазначения.ЗначениеРеквизитаОбъекта # карточка метода python $B show ЗначениеРеквизитаОбъекта # все модули, где есть метод с таким именем python $B module Пользователи # состав модуля целиком python $B modules контакт # какие вообще есть модули python $B subsystem печать # модули и механизмы подсистемы python $B overrides обновлен # переопределяемые обработчики под задачу python $B check Пользователи.ТекущийПользователь python $B stats # что вообще в справочнике
Общие ключи отбора: --av, --sub <подсистема>, --version 3.2.1, --limit N.
Как читать выдачу
Строка вида ОбщегоНазначения.ЗначениеРеквизитаОбъекта SFE - это модуль, метод и контексты.
Пометка [?] означает, что модуль выведен, а не подтвержден. Документация БСП называет
механизм, а не модуль, поэтому у части методов модуль восстановлен по примеру вызова или по
совпадению контекстов. В карточке (show) последняя строка всегда говорит, откуда взято имя
модуля. Метод с пометкой перед использованием стоит сверить с конфигурацией проекта.
Пометка стоит у 117 методов из 2624, это около четырех процентов. Еще у 37 модуль определить
не удалось вовсе - они собраны под именем ?. Это не значит, что метода нет: значит, одно и то же
имя объявлено в нескольких модулях, и документация не говорит, о каком из них статья.
Пометка [!] означает, что между версиями метод изменился. Карточка тогда содержит строку
"ВНИМАНИЕ, в <версия> иначе" с прежней сигнатурой. Таких методов 27, и часть изменений ломающие:
ОбщегоНазначения.ВыполнитьМетодКонфигурации из процедуры стал функцией, а у
ДобавитьПоказатель новый параметр вставлен не в конец, а первым. Код, написанный по новой
сигнатуре, на старой версии передаст аргументы не туда и об этом не сообщит.
Частые ошибки
- Выдуманный модуль. Проверять
check, а не полагаться на память. - Серверный метод в клиентском коде. Смотреть контексты; для клиента почти всегда есть
парный модуль с суффиксом
Клиент. - Вызов служебного модуля. Если в имени есть
Служебный- это не интерфейс. - Попытка вызвать переопределяемый обработчик. В него пишут тело, а не вызывают его.
- Метод из другой версии. У каждой записи указано, в каких версиях БСП она есть. Метод,
помеченный только
3.2.1, на 3.1.11 не существует. А метод с пометкой[!]существует в обеих, но вызывается по-разному - смотреть карточку до того, как писать вызов. - Расчет на то, что у метода тот же набор параметров, что был раньше. Сигнатура в справочнике полная, включая значения по умолчанию - брать оттуда.
Границы
Справочник знает ИМЕНА, СИГНАТУРЫ и КОНТЕКСТЫ, а назначение - строкой, написанной нами. Развернутого
описания в нем нет: текст документации ИТС лицензионный и сюда не переносится. Строка назначения есть
у каждого модуля, но у методов пока только у ядра - базовых модулей ОбщегоНазначения*, длительных
операций, пользователей, строковых функций, файловой системы и журнала регистрации. Когда нужно
понять механизм глубже, а не форму вызова - идти в документацию ИТС по подсистеме, которую покажет
subsystem.
Не покрыты: HTTP-сервисы и веб-сервисы библиотеки, макеты, роли, права, состав метаданных подсистем. Только программный интерфейс кода.
Сборка справочника
Готовый справочник лежит в references/bsp-api.jsonl и обновлять его нужно только при переходе
на новую версию БСП. Пересборка требует двух источников, оба лицензионные и в репозиторий не
входят: скрапа документации с ИТС и дистрибутива библиотеки.
bashpython -m v8unpack -E 1Cv8.cf E:\bsp\3_2_1 --temp E:\bsp\_tmp # распаковать дистрибутив python skills/1c-bsp-api/scripts/bsp-build.py \ --docs "3.1.11=E:\scrape\bsp3111doc" --docs "3.2.1=E:\scrape\bsp321doc" \ --lib "3.1.11=E:\bsp\3_1_11" --lib "3.2.1=E:\bsp\3_2_1" \ --purposes skills/1c-bsp-api/references/purposes.json \ --out skills/1c-bsp-api/references/bsp-api.jsonl \ --map skills/1c-bsp-api/references/subsystem-map.md
Формулировки назначения ведутся отдельно, в references/purposes.json: раздел modules и раздел
methods с ключами вида Модуль.Метод. При сборке они подмешиваются в справочник, а имена, которых
в нем нет, генератор называет в отчете - это ловит и опечатку, и формулировку к методу, которого
в этой версии уже не существует.
Ключи --docs и --lib указываются по одному на версию и связываются префиксом. Связывать
обязательно: если сшивать документацию 3.1.11 с библиотекой 3.2.1, методы, убранные в новой
версии, будут объявлены несуществующими. Библиотека без префикса версии берется для всех.
Брать надо 1Cv8.cf - чистую библиотеку, а не 1Cv8_demo.cf: демонстрационная конфигурация
несет объекты, которых в поставке нет. Распаковка идет без платформы и Конфигуратора.
Скрипты на Python, PowerShell-порта нет: сборка нужна редко, а поиск идет по готовому файлу.
