Документация для разработчиков

Shortcuts и x-callback-url

Автоматизируйте проверки пропускной способности, валидацию endpoints и сбор результатов с помощью встроенных действий и callback-endpoints.

Обзор

iPerf3 Client & Server предоставляет два уровня автоматизации:

Нативные действия Apple Shortcuts (рекомендуется для большинства пользователей)
Endpoints x-callback-url для сценариев межприложного взаимодействия

Базовая схема URL

Используйте iperf3cs://x-callback-url/... для автоматизации на основе callback.

Совместимость

Текущие требования к платформам Apple: iOS/iPadOS 16.6+, macOS 13.5+, visionOS 1.0+.

Встроенные действия Shortcuts

Эти действия доступны напрямую в приложении Apple Shortcuts:

Запустить тест iPerf

Запускает тест с настраиваемым сервером, протоколом, направлением и таймингом. Типичная длительность по умолчанию — 5 секунд.

Получить последний результат

Возвращает последний завершённый результат из локальной истории.

Проверить сервер

Проверяет доступность endpoint перед полным запуском.

Список серверов

Возвращает настроенные серверы для автоматизации с меню.

Endpoints x-callback-url

GETiperf3cs://x-callback-url/run-test

Запускает новый тест и опционально возвращает результат через callback-URL.

Параметр	Тип	Обязательный	Описание
`server`	String	Да	Имя хоста или IP адрес endpoint iPerf3.
`protocol`	String	Нет	`tcp` (по умолчанию) или `udp`.
`direction`	String	Нет	`download`, `upload` или `bidirectional`.
`durationSec`	Integer	Нет	Длительность в секундах. Типичное значение по умолчанию при автоматизации — 5.
`streams`	Integer	Нет	Количество параллельных потоков.
`x-success`	String	Нет	Callback-URL для успешной передачи результата.
`x-error`	String	Нет	Callback-URL для передачи ошибки.

GETiperf3cs://x-callback-url/get-last-result

Возвращает последний локальный результат — полезно для периодических рабочих процессов логирования.

Параметр	Тип	Обязательный	Описание
`x-success`	String	Нет	Callback-URL для успешной передачи данных.
`x-error`	String	Нет	Callback-URL для передачи ошибок.

GETiperf3cs://x-callback-url/test-server

Проверяет доступность endpoint и возвращает метаданные статуса/задержки.

Параметр	Тип	Обязательный	Описание
`server`	String	Да	Имя хоста или IP для тестирования.
`port`	Integer	Нет	Значение порта (по умолчанию 5201).

Примеры

Запуск теста с callbacks

 iperf3cs://x-callback-url/run-test?server=iperf.example.com&protocol=tcp&direction=download&durationSec=8&x-success=shortcuts://run-shortcut?name=StoreResult 

Чтение последнего результата

 iperf3cs://x-callback-url/get-last-result?x-success=shortcuts://run-shortcut?name=PushSummary 

Запуск из терминала на macOS

 open "iperf3cs://x-callback-url/run-test?server=10.0.1.5&protocol=udp&direction=bidirectional&durationSec=5" 

Типичные поля ответа

 {
  "testId": "A8B3D9",
  "timestamp": "2026-02-26T09:42:10Z",
  "server": "iperf.example.com",
  "protocol": "tcp",
  "downloadMbps": 942.7,
  "uploadMbps": 876.4,
  "status": "completed"
} 

Обработка ошибок

Когда действие завершается неудачно и присутствует x-error, callback получает объект ошибки.

Код	Описание
ERR_CONNECTION_FAILED	Не удалось подключиться к endpoint.
ERR_TIMEOUT	Соединение или тест превысили таймаут.
ERR_INVALID_SERVER	Некорректный хост или недостижимый адрес.
ERR_NO_RESULTS	Нет сохранённых результатов для запрошенного действия.
ERR_INVALID_PARAMS	Отсутствуют или неверны обязательные параметры.

 {
  "errorCode": "ERR_CONNECTION_FAILED",
  "errorMessage": "Could not reach iperf.example.com:5201"
} 

FAQ

Почему мой callback не возвращается в Shortcuts?

Убедитесь, что callback-URL закодированы в URL-формате и схема разрешена на вашем устройстве. Избегайте пробелов и неэкранированных символов в значениях параметров.

Могут ли тесты выполняться полностью в фоне?

Для надёжного выполнения держите приложение активным во время теста. Используйте планировщик Shortcuts для запуска в определённое время.

Какой паттерн интеграции наиболее безопасен?

Сначала используйте test-server, затем запускайте тест пропускной способности только при успешной проверке endpoint.

На главную Скачать приложение