OneScript (1С)
Пакет: wb-api-client на hub.oscript.io.
- OneScript: 2.0.0+
- HTTP: 1connector 2.3.3
- Зависимости: 1connector 2.3.3 — транспорт, jason 0.6.0 — сериализация моделей
- Обёртка секретов: класс
СекретнаяСтрока
Установка
opm install wb-api-clientЛибо подключите каталог пакета напрямую — например, склонировав соседний репозиторий на нужном теге:
git clone --branch v1.20260926.0 https://github.com/ValeryVerkhoturov/wb-api-client-1c.git#Использовать "путь/к/wb-api-client-1c"Где лежит исходник
Как и PHP, OneScript живёт в отдельном репозитории — ValeryVerkhoturov/wb-api-client-1c, подключённом к моно-репозиторию как git-submodule по пути clients/onescript. Так пользователи 1С могут склонировать только клиент, не утаскивая весь пайплайн, и поставить его из тега.
Ежедневный CI-прогон генерирует все восемь языков в одном месте, затем коммитит и тегает оба соседних репозитория одним и тем же тегом v<version>.
Как разделены категории
В OneScript нет пространств имён: имя класса глобально. Поэтому категории разделены именами, а не путями импорта:
- Классы API названы по категории — одна категория, один класс:
GeneralApi,ItemsApi,OrdersFbsApi,FinancesApi. Имена уникальны во всех 13 спецификациях, поэтому префикс им не нужен. - Классы моделей несут категорию префиксом:
ItemsResponse4XX,OrdersFbsResponse4XX. Без этого они бы столкнулись — одно только имяResponse4XXвстречается в 12 спецификациях из 13.
Файлы разложены по каталогам src/Классы/<Категория>/ и src/Модели/<Категория>/, но каталоги — только для чтения человеком: классы резолвит lib.config.
Один #Использовать подключает сразу все категории.
Авторизация
#Использовать "wb-api-client"
Настройки = Новый Конфигурация();
Настройки.УстановитьТокен("<ваш JWT WB>");
Клиент = Новый GeneralApi(Настройки);
Ответ = Клиент.GetPing();
Сообщить(Ответ.КодСостояния);
Сообщить(Ответ.Данные["Status"]);УстановитьТокен принимает и строку, и готовую СекретнаяСтрока.
Токен не раскрывается при выводе: у объекта нет экспортируемого свойства со значением, а Строка(Объект) в OneScript возвращает только имя класса.
Сообщить(Настройки.Токен()); // СекретнаяСтрока
Сообщить(Настройки.Токен().Раскрыть()); // eyJhbGciOi... (по запросу)Форма методов
Обязательные параметры передаются позиционно, необязательные — одной коллекцией последним аргументом:
Клиент = Новый ItemsApi(Настройки);
// Только тело запроса
Ответ = Клиент.PostV2CardsDeleteTrash(Тело);
// Тело + необязательные параметры строки запроса
Ответ = Клиент.PostV2CardsErrorList(Тело, Новый Структура("locale", "ru"));Ключи в ДопПараметры совпадают с именами из спецификации. Если имя не является допустимым идентификатором Структуры (например, содержит дефис — как заголовок X-Trace), передайте Соответствие:
ДопПараметры = Новый Соответствие;
ДопПараметры.Вставить("X-Trace", "trace-1");Ответ
Каждый метод возвращает ОтветAPI:
| Свойство / метод | Тип | Описание |
|---|---|---|
КодСостояния | Число | код состояния HTTP |
Данные | Произвольный | тело, разобранное из JSON |
Тело | Строка | тело ответа как есть |
Заголовки | Соответствие | заголовки ответа |
Успешно() | Булево | код 2xx |
ЭтоОшибка() | Булево | код 4xx или 5xx |
Заголовок(Имя) | Строка | поиск заголовка без учёта регистра |
Если тело не JSON (text/plain, application/zip), Данные будет Неопределено, а содержимое останется в Тело.
Обработка ошибок
По умолчанию ответы 4xx и 5xx приводят к исключению с текстом вида HTTP 404 — GET /api/v3/orders: <тело>.
ВызватьИсключение в OneScript не сохраняет объект для перехватчика — ОписаниеОшибки() вернул бы только имя класса, — поэтому отдельного класса исключения здесь нет: вся информация в тексте. Чтобы разобрать ошибку по полям, отключите выброс:
Настройки.ВыбрасыватьИсключениеПриОшибке = Ложь;
Ответ = Клиент.GetPing();
Если Ответ.ЭтоОшибка() Тогда
Сообщить(Ответ.КодСостояния);
Сообщить(Ответ.Данные["detail"]);
КонецЕсли;Адрес сервиса
У каждой категории WB свой хост, и он зашит в операцию. БазовыйURL по умолчанию пустой — это значит «брать адрес из спецификации». Заполните свойство, чтобы направить все запросы на другой хост, например на песочницу или тестовый стенд:
Настройки.БазовыйURL = "https://marketplace-api-sandbox.wildberries.ru";User-Agent и заголовки
Каждый запрос отправляет ValeryVerkhoturov/wb-api-client/onescript. Заменить или дополнить:
Настройки.ПользовательскийАгент = "MyApp/1.2.3 ValeryVerkhoturov/wb-api-client/onescript";
Настройки.ДополнительныеЗаголовки.Вставить("X-Request-Id", "…");Заголовки только ASCII
Значения заголовков должны состоять из символов ASCII — это ограничение HTTP-стека .NET, на котором работает OneScript. Кириллица в параметрах строки запроса, сегментах пути и теле запроса работает: они кодируются отдельно.
Таймаут и прокси
Настройки.Таймаут = 120; // секунды
Настройки.Прокси = Новый ИнтернетПрокси(Истина);Модели
Модели — классы со свойствами и парой методов преобразования. Незаполненные свойства в тело запроса не попадают, поэтому там не окажется null вместо отсутствующего поля.
Товар = Новый ItemsItem();
Товар.nmID = 123;
Товар.price = 1000;
Данные = Товар.Данные(); // Соответствие с именами из спецификации
// Обратно из ответа
Восстановленный = Новый ItemsItem(Ответ.Данные);Тело запроса можно передавать и как модель, и как обычное Соответствие / Структуру — транспорт разложит и то, и другое.
Чем сгенерировано
В openapi-generator нет генератора OneScript, поэтому он написан отдельно: ValeryVerkhoturov/onescript-openapi-generator — плагин, наследующий DefaultCodegen и подключаемый рядом с openapi-generator-cli.jar через META-INF/services. В основном репозитории он закреплён по коммиту, как и версия образа openapi-generator для остальных языков.
См. также
