¶ Работа с API Ринго
Ринго MDM предоставляет REST API для программного управления устройствами, профилями и командами. API документируется с помощью Swagger UI, что позволяет не только изучать доступные методы, но и тестировать их непосредственно в браузере.
В этом руководстве описано, как получить доступ к документации API, авторизоваться и начать работу с эндпоинтами.
¶ Требования
- Установленный и настроенный сервер Ринго MDM
- Доступ к серверу по SSH для получения учётных данных
- Учётная запись пользователя Ринго MDM с соответствующими правами
¶ Доступ к Swagger UI
Документация API доступна через веб-интерфейс Swagger UI по адресу:
https://[yourservername]/api/v1/documentation#/
Замените [yourservername] на фактическое доменное имя или IP-адрес вашего сервера Ринго MDM.
Важно! Для доступа к Swagger UI используется базовая HTTP-аутентификация. Без неё страница документации будет недоступна.
¶ Получение учётных данных для базовой аутентификации
Логин и пароль для доступа к Swagger UI хранятся на сервере Ринго MDM в файле конфигурации.
Подключитесь к серверу по SSH и выполните команду:
cat /etc/ringo/.env
Найдите в выводе строки с учётными данными:
DOCUMENTATION_LOGIN=your_username
DOCUMENTATION_PASSWORD=your_password
Используйте эти данные для входа в Swagger UI при открытии страницы документации.
¶ Авторизация в API
Для выполнения запросов к API необходимо получить токен авторизации. Swagger UI требует авторизации с использованием учётной записи пользователя Ринго MDM.
¶ Получение токена через терминал
Отправьте POST-запрос к эндпоинту /api/v1/auth с учётными данными пользователя Ринго:
curl -X POST https://[yourservername]/api/v1/auth \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "your_ringo_password"
}'
В ответе вы получите JSON с токеном:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Скопируйте значение токена — он понадобится для авторизации в Swagger UI.
¶ Получение токена в Swagger UI
Откройте скрытый список с эндпоинтом /api/v1/auth и укажите данные учётной записи, которые используете для авторизации в Ринго:
После выполнения запроса вы получите токен авторизации:
¶ Авторизация в Swagger UI
Найдите кнопку Authorize в правом верхнем углу интерфейса и нажмите на неё:
В открывшемся окне вставьте полученный токен в поле Value:
Нажмите кнопку Authorize, затем Close.
Теперь вы можете выполнять запросы ко всем эндпоинтам API непосредственно из интерфейса Swagger UI.
¶ Использование API
После успешной авторизации вы можете изучать доступные эндпоинты, их параметры и выполнять тестовые запросы прямо в браузере.
¶ Тестирование запроса
Выберите интересующий эндпоинт в списке.
Нажмите кнопку Try it out.
Заполните необходимые параметры запроса.
Нажмите Execute для отправки запроса.
Swagger UI отобразит полный запрос (curl-команду), ответ сервера и статус-код.
¶ Работа с API из кода
Вы можете использовать любой HTTP-клиент для работы с API Ринго MDM. Swagger UI генерирует примеры curl-команд для каждого эндпоинта, которые можно легко адаптировать для вашего языка программирования.
Пример запроса на получение списка устройств:
curl -X 'GET' \
'https://server.ringomdm.ru/api/v1/devices?page=1&os_type=macOS' \
-H 'accept: application/json' \
-H 'X-Auth-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiOTBjMjk3MzYtZDIyOS00ODg2LWE0ZDUtM2ViYTUzZWEyNzIzIiwiaWF0IjoxNzU5ODQyMTM4LCJleHAiOjE3NTk5Mjg1Mzh9.9hBqL5OnTSYlreS_Xt2F0Y463Gw9Lu1Et0q5ZpyieKQ'
Пример на Python:
import requests
url = "https://server.ringomdm.ru/api/v1/devices"
params = {
"page": 1,
"os_type": "macOS"
}
headers = {
"accept": "application/json",
"X-Auth-Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiOTBjMjk3MzYtZDIyOS00ODg2LWE0ZDUtM2ViYTUzZWEyNzIzIiwiaWF0IjoxNzU5ODQyMTM4LCJleHAiOjE3NTk5Mjg1Mzh9.9hBqL5OnTSYlreS_Xt2F0Y463Gw9Lu1Et0q5ZpyieKQ"
}
response = requests.get(url, headers=headers, params=params)
print("Status:", response.status_code)
try:
print(response.json())
except Exception:
print(response.text)
Совет. Токен имеет ограниченный срок действия. При получении ошибки
401 Unauthorizedполучите новый токен через/api/v1/auth.
¶ Выгрузка API swagger в json
Вы можете получить файл API в формате JSON, выполнив следующую команду:
curl https://FQDN/api/v1/documentation-json -o swagger.json