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

Runs a test and returns the result through the callback URLs.

Parámetro	Tipo	Requerido	Descripción
`serverId`	String	No	Saved server to use: `host:port`, a server UUID, or `default`. Omit it and the default server is used.
`serverName`	String	No	Pick the server by its saved name instead of `serverId`. Takes precedence when both are present.
`autoAdd`	Boolean	No	Create the server if it is not in the library yet. `addServer` is accepted as an alias.
`durationSec`	Integer	No	Test length in seconds. Defaults to 5.
`protocol`	String	No	`tcp` (default) or `udp`.
`direction`	String	No	`download`, `upload` or `bidirectional`.
`streams`	Integer	No	Parallel stream count.
`bandwidthMbps`	Number	No	Target bandwidth for UDP tests, in Mbps.
`format`	String	No	`json` (default) or `text`.
`x-success`	String	No	Callback URL. Receives `result` with the payload, or `resultRef` when the payload is too large to pass in a URL.
`x-error`	String	No	Callback URL. Receives `errorCode` and `errorMessage`.
`x-cancel`	String	No	Callback URL for a cancelled run.

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

Returns the most recent saved result. Useful for periodic logging.

Parámetro	Tipo	Requerido	Descripción
`serverId`	String	No	Limit the lookup to one server: `host:port`, a UUID, or `default`. Omit it for the latest result overall.
`serverName`	String	No	Same lookup by saved name. Takes precedence over `serverId`.
`format`	String	No	`json` (default) or `text`.
`x-success`	String	No	Callback URL. Receives `result` with the payload, or `resultRef` when the payload is too large to pass in a URL.
`x-error`	String	No	Callback URL. Receives `errorCode` and `errorMessage`.
`x-cancel`	String	No	Callback URL for a cancelled run.

GETiperf3cs://x-callback-url/fetch-result

Fetches a payload the app handed back as a reference. When a result is too large for a callback URL, the app returns <code>resultRef</code> instead of <code>result</code>, and this endpoint exchanges that reference for the full payload.

Parámetro	Tipo	Requerido	Descripción
`resultRef`	String	Sí	Reference returned earlier in place of `result`.
`format`	String	No	`json` (default) or `text`.
`x-success`	String	No	Callback URL. Receives `result` with the payload, or `resultRef` when the payload is too large to pass in a URL.
`x-error`	String	No	Callback URL. Receives `errorCode` and `errorMessage`.
`x-cancel`	String	No	Callback URL for a cancelled run.

Ejemplos

Ejecutar prueba con callbacks

 iperf3cs://x-callback-url/run-test?serverId=iperf.example.com:5201&autoAdd=1&protocol=tcp&direction=download&durationSec=8&format=json&x-success=shortcuts://run-shortcut?name=StoreResult 

Leer el último resultado

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

Lanzamiento desde terminal en macOS

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

Campos típicos de la carga útil

 {
  "success": true,
  "startTime": "2026-08-21T09:42:02Z",
  "endTime": "2026-08-21T09:42:10Z",
  "duration": 8,
  "receivedMegabitsPerSecond": 942.7,
  "sentMegabitsPerSecond": 876.4,
  "receivedBytes": 942700000,
  "summaryText": "942.7 Mbps down, 876.4 Mbps up"
} 

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
invalidParameter	A parameter is missing, malformed or out of range.
serverNotFound	No saved server matched the lookup, and `autoAdd` was not set.
networkUnavailable	The device has no usable network path to the endpoint.
connectionTimeout	The connection or the test exceeded its timeout.
testFailed	The test started and ended without a usable result.
cancelled	The run was cancelled before it finished.
requiresAppOpen	The action needs the app in the foreground.
unsupportedOnOSVersion	The action is not available on this OS version.

 {
  "errorCode": "serverNotFound",
  "errorMessage": "No saved server matches 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?

Define x-error en cada llamada y ramifica según errorCode. Empieza con una ejecución corta durationSec=5: si devuelve serverNotFound o connectionTimeout, no tiene sentido lanzar una prueba larga.

Volver al inicio Descargar app