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

Lance un nouveau test et retourne optionnellement via des URLs de callback.

Paramètre	Type	Requis	Description
`server`	String	Oui	Nom d'hôte ou IP de l'endpoint iPerf3.
`protocol`	String	Non	`tcp` (par défaut) ou `udp`.
`direction`	String	Non	`download`, `upload` ou `bidirectional`.
`durationSec`	Integer	Non	Durée en secondes. La valeur par défaut courante en automatisation est 5.
`streams`	Integer	Non	Nombre de flux parallèles.
`x-success`	String	Non	URL de callback pour le payload de résultat réussi.
`x-error`	String	Non	URL de callback pour le payload d'erreur.

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

Retourne le dernier résultat local, utile pour les workflows de journalisation périodique.

Paramètre	Type	Requis	Description
`x-success`	String	Non	URL de callback pour le payload réussi.
`x-error`	String	Non	URL de callback pour les erreurs.

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

Vérifie l'accessibilité de l'endpoint et retourne les métadonnées de statut/latence.

Paramètre	Type	Requis	Description
`server`	String	Oui	Nom d'hôte ou IP à tester.
`port`	Integer	Non	Valeur du port (par défaut 5201).

Exemples

Lancer un test avec callbacks

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

Lire le dernier résultat

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

Lancement Terminal sur macOS

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

Champs de payload typiques

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

Gestion des erreurs

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

Code	Description
ERR_CONNECTION_FAILED	Impossible de se connecter à l'endpoint.
ERR_TIMEOUT	La connexion ou le test a dépassé le délai d'attente.
ERR_INVALID_SERVER	Hôte mal formé ou adresse inaccessible.
ERR_NO_RESULTS	Aucun résultat sauvegardé pour l'action demandée.
ERR_INVALID_PARAMS	Paramètres requis manquants ou invalides.

 {
  "errorCode": "ERR_CONNECTION_FAILED",
  "errorMessage": "Could not reach 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 ?

Utilisez test-server d'abord, puis lancez un test de débit uniquement si la vérification de l'endpoint réussit.

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