Модели оборудования
Все операции. Авторизация. Запросы и повторы.
Все пути в этом файле дополняют /api/v1 на домене организации.
Описание и ограничения
Назначение
Справочник моделей и модификаций, общий для экземпляров оборудования организации.
Поля и назначение
| Публичное поле | Формат и смысл | Доступ |
|---|---|---|
id |
UUID, не числовой ID | только чтение |
manufacturer_id |
id производителя |
чтение и запись |
device_type_id |
id вида оборудования |
чтение и запись |
model_name |
обязательная строка | чтение и запись |
modification, firmware |
строки/null | чтение и запись |
version, updated_at |
строка Unix-секунд и UTC timestamp/null | только чтение |
Обязательность и null указаны в схемах каждой операции ниже.
Доступ и выборка
Нужны equipment_models:read/write, права «ТОиР — Оборудование → Просмотр, Изменение» и доступ к ТОиР. Производитель и тип должны быть доступны организации; отдельное разрешение чтения справочников для их выбора не требуется. Повтор запроса проверяет текущие права и доступ к модели.
Фильтры: filter[manufacturer_id], filter[device_type_id], filter[model_name], filter[q]; model_name — точное обозначение, q ищет по модели, модификации и прошивке. Пагинация по курсору с сортировкой id/-id сохраняет UUID строкой. Неизвестные параметры запроса отклоняются; GET карточки поддерживает ETag/304.
Для создания обязательны manufacturer_id, device_type_id и model_name. Первые два поля — положительные целые числа JSON; model_name — непустая строка до 255 символов. modification и firmware допускают строки до 255 символов или null, по умолчанию null. Пробелы по краям обозначений удаляются; регистр, пунктуация и внутренние пробелы сохраняются. Пустые модификация и прошивка возвращаются как null. Успех — 201 с карточкой.
Для изменения нужен If-Resource-Version модели. Отсутствующие поля сохраняются. Если после удаления пробелов по краям значения не изменились, версия сохраняется и событие не создаётся. Принимаются только поля из схемы запроса. Успех — 200 с карточкой.
Операции
| Метод | Путь | Назначение |
|---|---|---|
| GET | /equipment-models |
Список с фильтрами и пагинацией |
| POST | /equipment-models |
Создание |
| GET | /equipment-models/{id} |
Карточка |
| POST | /equipment-models/{id}/update |
Изменение разрешённых полей |
GET /equipment-models
Список с фильтрами и пагинацией.
Доступ. Разрешения подключения: equipment_models:read. Права сотрудника: «ТОиР — Оборудование → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
filter[q] |
параметр запроса | строка | нет | нет | не более 200 символов |
sort |
параметр запроса | строка | нет | нет | Допустимо: "id", "-id" |
page[size] |
параметр запроса | целое число | нет | нет | ≥ 1; ≤ 100 |
page[cursor] |
параметр запроса | строка | нет | нет | не более 8192 символов |
filter[manufacturer_id] |
параметр запроса | целое число | нет | нет | ≥ 1 |
filter[device_type_id] |
параметр запроса | целое число | нет | нет | ≥ 1 |
filter[model_name] |
параметр запроса | строка | нет | нет | не более 255 символов |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff \
"$API/equipment-models" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json"
POST /equipment-models
Создание.
Доступ. Разрешения подключения: equipment_models:write. Права сотрудника: «ТОиР — Оборудование → Изменение». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
Idempotency-Key |
заголовок | строка | да | нет | не менее 1 символов; не более 128 символов; Шаблон: ^[A-Za-z0-9._:-]+$ |
Тело запроса
Content-Type: application/json. Тело обязательно.
| Поле | Тип | Обязательно | null | Ограничения и смысл |
|---|---|---|---|---|
manufacturer_id |
целое число | да | нет | ≥ 1 |
device_type_id |
целое число | да | нет | ≥ 1 |
model_name |
строка | да | нет | не более 255 символов |
modification |
строка / null | нет | да | не более 255 символов |
firmware |
строка / null | нет | да | не более 255 символов |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 201 | Создано. Полная схема и пример |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 404 | Не найдено или недоступно. Коды и формат ошибки |
| 409 | Конфликт состояния или повтора. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
| HTTP | Заголовок ответа | Тип | Описание |
|---|---|---|---|
| 201 | Location |
строка | |
| 201 | Idempotency-Replayed |
строка |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
У принятого POST Location и meta.operation_id указывают на журнал операции; ETag отсутствует. При повторе запроса сохраняются исходные data/meta, добавляется Idempotency-Replayed: true. Версии передавайте по назначению, указанному в описании ресурса.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff --request POST \
"$API/equipment-models" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json" \
--header "Idempotency-Key: example:v1-equipment-models-create:001" \
--header "Content-Type: application/json" \
--data-binary '@examples/requests/v1.equipment-models.create.json'
GET /equipment-models/{id}
Карточка.
Доступ. Разрешения подключения: equipment_models:read. Права сотрудника: «ТОиР — Оборудование → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
id |
путь | строка | да | нет | Шаблон: ^(?:[\da-fA-F]{8}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{12})$ |
If-None-Match |
заголовок | строка | нет | нет | — |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 304 | Представление не изменилось, без тела. Условный GET |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 404 | Не найдено или недоступно. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
| HTTP | Заголовок ответа | Тип | Описание |
|---|---|---|---|
| 200 | ETag |
строка |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff \
"$API/equipment-models/ef62763b-87f9-4c90-83bb-e919f3c8e111" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json"
POST /equipment-models/{id}/update
Изменение разрешённых полей.
Доступ. Разрешения подключения: equipment_models:write. Права сотрудника: «ТОиР — Оборудование → Изменение». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
id |
путь | строка | да | нет | Шаблон: ^(?:[\da-fA-F]{8}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{12})$ |
Idempotency-Key |
заголовок | строка | да | нет | не менее 1 символов; не более 128 символов; Шаблон: ^[A-Za-z0-9._:-]+$ |
If-Resource-Version |
заголовок | строка | да | нет | не менее 1 символов; не более 128 символов; Шаблон: ^[A-Za-z0-9._~-]+$ |
Тело запроса
Content-Type: application/json. Тело обязательно.
| Поле | Тип | Обязательно | null | Ограничения и смысл |
|---|---|---|---|---|
manufacturer_id |
целое число | нет | нет | ≥ 1 |
device_type_id |
целое число | нет | нет | ≥ 1 |
model_name |
строка | нет | нет | не более 255 символов |
modification |
строка / null | нет | да | не более 255 символов |
firmware |
строка / null | нет | да | не более 255 символов |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 404 | Не найдено или недоступно. Коды и формат ошибки |
| 409 | Конфликт состояния или повтора. Коды и формат ошибки |
| 412 | Версия устарела. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 428 | Нужно предусловие версии. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
| HTTP | Заголовок ответа | Тип | Описание |
|---|---|---|---|
| 200 | Location |
строка | |
| 200 | Idempotency-Replayed |
строка |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
У принятого POST Location и meta.operation_id указывают на журнал операции; ETag отсутствует. При повторе запроса сохраняются исходные data/meta, добавляется Idempotency-Replayed: true. Версии передавайте по назначению, указанному в описании ресурса.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff --request POST \
"$API/equipment-models/ef62763b-87f9-4c90-83bb-e919f3c8e111/update" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json" \
--header "Idempotency-Key: example:v1-equipment-models-update:001" \
--header "If-Resource-Version: $RESOURCE_VERSION" \
--header "Content-Type: application/json" \
--data-binary '@examples/requests/v1.equipment-models.update.json'