Documentación para desarrolladores

Atajos y x-callback-url

Automatiza comprobaciones de rendimiento, validación de endpoints y recopilación de resultados con acciones integradas y endpoints de callback.

Descripción general

iPerf3 Client & Server expone dos capas de automatización:

Acciones nativas de Atajos de Apple (recomendado para la mayoría de los usuarios)
Endpoints x-callback-url para flujos de trabajo de app a app programables

Esquema de URL base

Usa iperf3cs://x-callback-url/... para automatización basada en callbacks.

Compatibilidad

Los requisitos actuales de la plataforma Apple son iOS/iPadOS 16.6+, macOS 13.5+ y visionOS 1.0+.

Acciones de Atajos integradas

Estas acciones están disponibles directamente en la app Atajos de Apple:

Ejecutar prueba iPerf

Ejecuta una prueba con servidor, protocolo, dirección y tiempo configurables. La duración predeterminada típica en el flujo de Atajos es 5 segundos.

Obtener último resultado

Devuelve el resultado completado más reciente del historial local.

Probar servidor

Comprueba la disponibilidad del endpoint antes de una ejecución completa.

Listar servidores

Devuelve los servidores configurados para automatización basada en menús.

Endpoints x-callback-url

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

Inicia una nueva prueba y opcionalmente vuelve mediante URLs de callback.

Parámetro	Tipo	Requerido	Descripción
`server`	String	Sí	Nombre de host o IP del endpoint iPerf3.
`protocol`	String	No	`tcp` (predeterminado) o `udp`.
`direction`	String	No	`download`, `upload` o `bidirectional`.
`durationSec`	Integer	No	Duración en segundos. El valor predeterminado habitual en automatización es 5.
`streams`	Integer	No	Número de flujos paralelos.
`x-success`	String	No	URL de callback para la carga útil de resultado exitoso.
`x-error`	String	No	URL de callback para la carga útil de error.

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

Devuelve el último resultado local, útil para flujos de trabajo de registro periódico.

Parámetro	Tipo	Requerido	Descripción
`x-success`	String	No	URL de callback para la carga útil exitosa.
`x-error`	String	No	URL de callback para errores.

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

Comprueba la accesibilidad del endpoint y devuelve metadatos de estado/latencia.

Parámetro	Tipo	Requerido	Descripción
`server`	String	Sí	Nombre de host o IP a probar.
`port`	Integer	No	Valor del puerto (predeterminado 5201).

Ejemplos

Ejecutar prueba con callbacks

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

Leer el último resultado

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

Lanzamiento desde terminal en macOS

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

Campos típicos de la carga útil

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

Gestión de errores

Cuando una acción falla y x-error está presente, el callback recibe un objeto de error.

Código	Descripción
ERR_CONNECTION_FAILED	No se puede conectar al endpoint.
ERR_TIMEOUT	La conexión o la prueba superó el tiempo de espera.
ERR_INVALID_SERVER	Host con formato incorrecto o dirección inalcanzable.
ERR_NO_RESULTS	No hay resultados guardados para la acción solicitada.
ERR_INVALID_PARAMS	Parámetros requeridos faltantes o no válidos.

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

Preguntas frecuentes

¿Por qué mi callback no regresa a Atajos?

Asegúrate de que las URLs de callback estén codificadas en URL y que el esquema esté permitido en tu dispositivo. Evita espacios o símbolos sin escapar en los valores de consulta.

¿Pueden las pruebas ejecutarse completamente en segundo plano?

Para una ejecución confiable, mantén la app activa durante el tiempo de ejecución de la prueba. Usa la programación de Atajos para activar ejecuciones en momentos específicos.

¿Cuál es el patrón de integración más seguro?

Usa test-server primero, luego ejecuta una prueba de rendimiento solo si la comprobación del endpoint es exitosa.

Volver al inicio Descargar app