Перед началом
- Учебная установка BOX 3.2 и её адрес от администратора. Нужны доступ к Swagger и учётная запись с правами для выбранных запросов.
- Браузер и HTTP-клиент: Swagger UI, curl или привычный инструмент. Базовые знания HTTP, JSON и заголовка Authorization.
- OpenAPI именно этой сборки. Проверьте наличие методов до выполнения примеров.
Пути запросов ниже опубликованы в руководстве BOX 3.x. Состав методов, авторизация и ответы зависят от сборки и прав. Для BOX 5.0 начните с отдельного справочника и OpenAPI своей установки; применимость этих путей к BOX 5.0 здесь не утверждается.
Шаг 1 из 4
Откройте схему установленной версии
Найдите описание API, по которому будете строить запросы.
- Откройте /api/docs/ на адресе своей установки. При необходимости загрузите её OpenAPI-схему по /api/swagger.json.
- Найдите GET /api/base/ping/ и GET /api/statistics/auth/me/. Прочитайте требования к авторизации, параметры и описания ответов.
- Запишите версию установки и дату получения схемы. Если метода нет, уточните поставку и выберите поддерживаемый запрос вместе с администратором.
Оба метода найдены в актуальной схеме; известны способ доступа и ожидаемые ответы.
Что проверить, если результат отличается
Ошибка открытия Swagger может быть связана с адресом, маршрутизацией, доступом или составом поставки. Текст примера не заменяет схему работающей установки.
Шаг 2 из 4
Проверьте доступность API
Выполните первый запрос чтения и сопоставьте ответ со схемой.
curl 'https://<box-host>/api/base/ping/'- Замените <box-host> адресом своей учебной установки. Выполните запрос в Swagger или HTTP-клиенте; используйте авторизацию, если она требуется вашей схемой.
- Зафиксируйте HTTP-статус и тело ответа. Сравните их с описанием метода в OpenAPI.
Получен ответ от нужной установки. Статус и формат сопоставлены с описанием метода.
Что проверить, если результат отличается
Сначала различите сетевую ошибку, ответ HTTP и прикладную ошибку в теле. Успешный ping ещё не подтверждает права на камеры, события и остальные ресурсы.
Шаг 3 из 4
Проверьте авторизацию чтением профиля
Убедитесь, от имени какой учётной записи выполняются запросы.
curl -H 'Authorization: Bearer <access_token>' \
'https://<box-host>/api/statistics/auth/me/'- По схеме установки выполните авторизацию в Swagger. В опубликованной документации описан OAuth2 Password Flow через POST /api/statistics/auth/login/; поля и требования берите из своего OpenAPI.
- Вызовите GET /api/statistics/auth/me/. Для клиента вне Swagger передайте полученный токен в заголовке Bearer.
- Сопоставьте сведения о текущем пользователе с учебной учётной записью. В записи результата оставьте только нужные технические сведения; исключите токен, пароль и персональные данные.
Ответ соответствует схеме и нужной учётной записи. Понятны способ авторизации и границы выданных прав.
Что проверить, если результат отличается
При отказе проверьте срок действия токена и права по правилам своей установки. Сохраняйте код и описание ошибки, чтобы отличить проблему авторизации от отсутствующего метода.
Шаг 4 из 4
Опишите параметры следующего запроса и ожидаемый ответ
Подготовьте чтение нужных интеграции данных.
- Выберите в OpenAPI поддерживаемый метод чтения нужного ресурса: например, камер или событий. Запишите точный путь и права; в разных сборках набор методов различается.
- Уточните фильтры, пагинацию, формат времени и идентификаторы. Если данных пока нет, согласуйте тестовую запись на учебной установке.
- Составьте примеры ожидаемого ответа, пустой выборки и ошибки доступа по фактической схеме. Выполнение дополнительных запросов оставьте в границах выданных прав.
Для следующего метода определены вход, ответ, права и разбор ошибок. Неопределённые поля вынесены на уточнение.
Что проверить, если результат отличается
Пример структуры события описывает смысл полей. Транспорт, точный JSON и адрес получателя определяются правилами обмена данными конкретной интеграции.
Закрепите результат
Самостоятельная работа
Сначала выполните задание и запишите вывод, затем откройте критерий самопроверки.
1. Разберите отказ авторизации
Для метода чтения, который требует авторизацию, выполните запрос без токена на учебной установке. Сравните фактический ответ с описанием ошибки в OpenAPI.
Критерий самопроверки
Вы можете назвать статус и причину отказа, а затем повторить тот же запрос с корректной авторизацией. Пароли и токены не попали в журнал упражнения.
2. Подготовьте чтение списка
По схеме выбранного метода опишите обработку непустой и пустой выборки, а также переход к следующей странице, если метод поддерживает пагинацию.
Критерий самопроверки
Использованы точные поля вашей схемы. Отсутствие данных отличается от ошибки запроса; единицы времени и порядок сортировки уточнены.
Результат маршрута
Соберите короткую запись о выполнении. По ней должно быть понятно, что проверено, с какими данными и что ещё требует работы.
- Версия установки и дата используемой OpenAPI-схемы.
- Методы, параметры и требования к правам для выполненных запросов.
- Фактические HTTP-статусы и примеры ответов без секретов и персональных данных.
- Правила обработки пустого ответа, ошибки доступа и сетевого сбоя.
- Параметры следующего запроса, ожидаемый ответ и открытые вопросы к интеграции.