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

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

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

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

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

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

Parameter	Typ	Erforderlich	Beschreibung
`resultRef`	String	Ja	Reference returned earlier in place of `result`.
`format`	String	Nein	`json` (default) or `text`.
`x-success`	String	Nein	Callback URL. Receives `result` with the payload, or `resultRef` when the payload is too large to pass in a URL.
`x-error`	String	Nein	Callback URL. Receives `errorCode` and `errorMessage`.
`x-cancel`	String	Nein	Callback URL for a cancelled run.

Beispiele

Test mit Callbacks ausführen

 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 

Neuestes Ergebnis lesen

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

Terminal-Start unter macOS

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

Typische Payload-Felder

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

Fehlerbehandlung

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

Code	Beschreibung
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

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?

Setze x-error bei jedem Aufruf und verzweige über errorCode. Beginne mit einem kurzen Lauf durationSec=5: Kommt serverNotFound oder connectionTimeout zurück, lohnt kein langer Test.

Zurück zur Startseite App herunterladen