Documentation développeur

Shortcuts et x-callback-url

Automatisez les vérifications de débit, la validation des endpoints et la collecte de résultats avec des actions intégrées et des endpoints callback.

Vue d'ensemble

iPerf3 Client & Server expose deux couches d'automatisation :

Actions Apple Shortcuts natives (recommandé pour la plupart des utilisateurs)
Endpoints x-callback-url pour les workflows scriptables d'application à application

Schéma d'URL de base

Utilisez iperf3cs://x-callback-url/... pour l'automatisation basée sur callback.

Compatibilité

Exigences actuelles de la plateforme Apple : iOS/iPadOS 16.6+, macOS 13.5+ et visionOS 1.0+.

Actions Shortcuts intégrées

Ces actions sont disponibles directement dans l'application Apple Shortcuts :

Lancer un test iPerf

Lance un test avec un serveur, un protocole, une direction et un timing configurables. La durée par défaut typique dans le flux Shortcuts est de 5 secondes.

Obtenir le dernier résultat

Retourne le dernier résultat complété depuis l'historique local.

Tester le serveur

Vérifie la disponibilité de l'endpoint avant un lancement complet.

Lister les serveurs

Retourne les serveurs configurés pour l'automatisation pilotée par menu.

Endpoints x-callback-url

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

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

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

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

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

Paramètre	Type	Requis	Description
`serverId`	String	Non	Limit the lookup to one server: `host:port`, a UUID, or `default`. Omit it for the latest result overall.
`serverName`	String	Non	Same lookup by saved name. Takes precedence over `serverId`.
`format`	String	Non	`json` (default) or `text`.
`x-success`	String	Non	Callback URL. Receives `result` with the payload, or `resultRef` when the payload is too large to pass in a URL.
`x-error`	String	Non	Callback URL. Receives `errorCode` and `errorMessage`.
`x-cancel`	String	Non	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.

Paramètre	Type	Requis	Description
`resultRef`	String	Oui	Reference returned earlier in place of `result`.
`format`	String	Non	`json` (default) or `text`.
`x-success`	String	Non	Callback URL. Receives `result` with the payload, or `resultRef` when the payload is too large to pass in a URL.
`x-error`	String	Non	Callback URL. Receives `errorCode` and `errorMessage`.
`x-cancel`	String	Non	Callback URL for a cancelled run.

Exemples

Lancer un test avec 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 

Lire le dernier résultat

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

Lancement Terminal sur macOS

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

Champs de payload typiques

 {
  "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"
} 

Gestion des erreurs

Quand une action échoue et que x-error est présent, le callback reçoit un objet d'erreur.

Code	Description
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"
} 

FAQ

Pourquoi mon callback ne revient-il pas à Shortcuts ?

Assurez-vous que les URLs de callback sont encodées en URL et que le schéma est autorisé sur votre appareil. Évitez les espaces ou symboles non échappés dans les valeurs de requête.

Les tests peuvent-ils s'exécuter entièrement en arrière-plan ?

Pour une exécution fiable, gardez l'application active pendant la durée du test. Utilisez la planification Shortcuts pour déclencher des exécutions à des moments spécifiques.

Quel est le schéma d'intégration le plus sûr ?

Renseignez x-error à chaque appel et branchez sur errorCode. Commencez par un test court durationSec=5 : s'il renvoie serverNotFound ou connectionTimeout, inutile de lancer un test long.

Retour à l'accueil Télécharger l'application