Entwicklerdokumentation

Shortcuts und x-callback-url

Durchsatzprüfungen, Endpunktvalidierung und Ergebniserfassung mit integrierten Aktionen und Callback-Endpunkten automatisieren.

Übersicht

iPerf3 Client & Server bietet zwei Automatisierungsebenen:

Native Apple-Shortcuts-Aktionen (für die meisten Nutzer empfohlen)
x-callback-url-Endpunkte für skriptbasierte App-zu-App-Workflows

Basis-URL-Schema

iperf3cs://x-callback-url/... für callback-basierte Automatisierung verwenden.

Kompatibilität

Aktuelle Apple-Plattformanforderungen: iOS/iPadOS 16.6+, macOS 13.5+ und visionOS 1.0+.

Integrierte Shortcuts-Aktionen

Diese Aktionen sind direkt in der Apple-Shortcuts-App verfügbar:

iPerf-Test ausführen

Führt einen Test mit konfigurierbarem Server, Protokoll, Richtung und Timing aus. Typische Standardlaufzeit im Shortcuts-Ablauf beträgt 5 Sekunden.

Letztes Ergebnis abrufen

Gibt das neueste abgeschlossene Ergebnis aus dem lokalen Verlauf zurück.

Server testen

Prüft Endpunktverfügbarkeit vor einem vollständigen Lauf.

Server auflisten

Gibt konfigurierte Server für menügesteuerte Automatisierung zurück.

x-callback-url-Endpunkte

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

Startet einen neuen Test und kehrt optional über Callback-URLs zurück.

Parameter	Typ	Erforderlich	Beschreibung
`server`	String	Ja	Hostname oder IP des iPerf3-Endpunkts.
`protocol`	String	Nein	`tcp` (Standard) oder `udp`.
`direction`	String	Nein	`download`, `upload` oder `bidirectional`.
`durationSec`	Integer	Nein	Laufzeit in Sekunden. Üblicher Standard in der Automatisierung ist 5.
`streams`	Integer	Nein	Anzahl paralleler Streams.
`x-success`	String	Nein	Callback-URL für erfolgreiche Ergebnis-Payload.
`x-error`	String	Nein	Callback-URL für Fehler-Payload.

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

Gibt das neueste lokale Ergebnis zurück, nützlich für periodische Logging-Workflows.

Parameter	Typ	Erforderlich	Beschreibung
`x-success`	String	Nein	Callback-URL für erfolgreiche Payload.
`x-error`	String	Nein	Callback-URL für Fehler.

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

Prüft Endpunkt-Erreichbarkeit und gibt Status-/Latenz-Metadaten zurück.

Parameter	Typ	Erforderlich	Beschreibung
`server`	String	Ja	Hostname oder IP zum Testen.
`port`	Integer	Nein	Port-Wert (Standard 5201).

Beispiele

Test mit Callbacks ausführen

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

Neuestes Ergebnis lesen

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

Terminal-Start unter macOS

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

Typische Payload-Felder

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

Fehlerbehandlung

Wenn eine Aktion fehlschlägt und x-error vorhanden ist, erhält der Callback ein Fehlerobjekt.

Code	Beschreibung
ERR_CONNECTION_FAILED	Verbindung zum Endpunkt nicht möglich.
ERR_TIMEOUT	Verbindung oder Test hat Timeout überschritten.
ERR_INVALID_SERVER	Fehlerhafte Host-Angabe oder nicht erreichbare Adresse.
ERR_NO_RESULTS	Keine gespeicherten Ergebnisse für die angeforderte Aktion.
ERR_INVALID_PARAMS	Fehlende oder ungültige Pflichtparameter.

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

FAQ

Warum kehrt mein Callback nicht zu Shortcuts zurück?

Sicherstellen, dass Callback-URLs URL-kodiert sind und das Schema auf dem Gerät erlaubt ist. Leerzeichen oder nicht maskierte Symbole in Abfragewerten vermeiden.

Können Tests vollständig im Hintergrund laufen?

Für zuverlässige Ausführung die App während der Testlaufzeit aktiv halten. Shortcuts-Planung nutzen, um Läufe zu bestimmten Zeiten auszulösen.

Was ist das sicherste Integrationsmuster?

Zuerst test-server verwenden, dann nur bei erfolgreichem Endpunkt-Check einen Durchsatztest ausführen.

Zurück zur Startseite App herunterladen