Ontwikkelaarsdocumentatie

Shortcuts en x-callback-url

Automatiseer doorvoercontroles, eindpuntvalidatie en resultaatverzameling met ingebouwde acties en callback-eindpunten.

Overzicht

iPerf3 Client & Server biedt twee automatiseringslagen:

Native Apple Shortcuts-acties (aanbevolen voor de meeste gebruikers)
x-callback-url-eindpunten voor scriptbare app-naar-app-workflows

Basis URL-schema

Gebruik iperf3cs://x-callback-url/... voor callback-gebaseerde automatisering.

Compatibiliteit

De huidige Apple-platformvereisten zijn iOS/iPadOS 16.6+, macOS 13.5+ en visionOS 1.0+.

Ingebouwde Shortcuts-acties

Deze acties zijn direct beschikbaar in de Apple Shortcuts-app:

iPerf-test uitvoeren

Voert een test uit met configureerbare server, protocol, richting en timing. Typische standaardduur in de Shortcuts-workflow is 5 seconden.

Laatste resultaat ophalen

Retourneert het meest recente voltooide resultaat uit de lokale geschiedenis.

Server testen

Controleert de beschikbaarheid van eindpunten vóór een volledige run.

Servers weergeven

Retourneert geconfigureerde servers voor menu-gestuurde automatisering.

x-callback-url Eindpunten

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

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

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

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

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

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

Voorbeelden

Test uitvoeren met 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 

Meest recente resultaat lezen

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

Terminal starten op macOS

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

Typische payload-velden

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

Foutafhandeling

Wanneer een actie mislukt en x-error aanwezig is, ontvangt de callback een foutobject.

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

Waarom keert mijn callback niet terug naar Shortcuts?

Zorg ervoor dat callback-URL's URL-gecodeerd zijn en het schema is toegestaan op uw apparaat. Vermijd spaties of niet-geëscapete symbolen in querywaarden.

Kunnen tests volledig op de achtergrond worden uitgevoerd?

Voor betrouwbare uitvoering, houd de app actief tijdens de testduur. Gebruik Shortcuts-planning om runs op specifieke tijden te triggeren.

Wat is het veiligste integratiepatroon?

Zet x-error bij elke aanroep en vertak op errorCode. Begin met een korte run durationSec=5: komt serverNotFound of connectionTimeout terug, dan heeft een lange test geen zin.

Terug naar startpagina App downloaden