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

Start een nieuwe test en retourneert optioneel via callback-URL's.

Parameter	Type	Vereist	Beschrijving
`server`	String	Ja	Hostnaam of IP van het iPerf3-eindpunt.
`protocol`	String	Nee	`tcp` (standaard) of `udp`.
`direction`	String	Nee	`download`, `upload` of `bidirectional`.
`durationSec`	Integer	Nee	Duur in seconden. Veelgebruikte standaard bij automatisering is 5.
`streams`	Integer	Nee	Aantal parallelle streams.
`x-success`	String	Nee	Callback-URL voor succesvolle resultaten.
`x-error`	String	Nee	Callback-URL voor foutmeldingen.

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

Retourneert het meest recente lokale resultaat, handig voor periodieke logworkflows.

Parameter	Type	Vereist	Beschrijving
`x-success`	String	Nee	Callback-URL voor succesvolle resultaten.
`x-error`	String	Nee	Callback-URL voor fouten.

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

Controleert de bereikbaarheid van eindpunten en retourneert status/latentiemetadata.

Parameter	Type	Vereist	Beschrijving
`server`	String	Ja	Hostnaam of IP om te testen.
`port`	Integer	Nee	Poortwaarde (standaard 5201).

Voorbeelden

Test uitvoeren met callbacks

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

Meest recente resultaat lezen

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

Terminal starten op macOS

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

Typische payload-velden

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

Foutafhandeling

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

Code	Beschrijving
ERR_CONNECTION_FAILED	Kan geen verbinding maken met eindpunt.
ERR_TIMEOUT	Verbinding of test heeft de time-out overschreden.
ERR_INVALID_SERVER	Onjuist samengestelde host of onbereikbaar adres.
ERR_NO_RESULTS	Geen opgeslagen resultaten voor de gevraagde actie.
ERR_INVALID_PARAMS	Ontbrekende of ongeldige vereiste parameters.

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

Gebruik eerst test-server, voer vervolgens een doorvoertest uit als de eindpuntcontrole slaagt.

Terug naar startpagina App downloaden