Fejlesztői dokumentáció

Shortcuts és x-callback-url

Automatizáld az átviteli sebesség ellenőrzéseket, a végpont-validálást és az eredmények gyűjtését beépített műveletekkel és visszahívási végpontokkal.

Áttekintés

Az iPerf3 Client & Server két automatizálási réteget tesz elérhetővé:

Natív Apple Shortcuts műveletek (legtöbb felhasználónak ajánlott)
x-callback-url végpontok szkriptelhető alkalmazásközi munkafolyamatokhoz

Alap URL-séma

Használd az iperf3cs://x-callback-url/... sémát visszahívás-alapú automatizáláshoz.

Kompatibilitás

Az aktuális Apple platformkövetelmények: iOS/iPadOS 16.6+, macOS 13.5+ és visionOS 1.0+.

Beépített Shortcuts műveletek

Ezek a műveletek közvetlenül elérhetők az Apple Shortcuts alkalmazásban:

iPerf teszt futtatása

Tesztet futtat konfigurálható szerverrel, protokollal, iránnyal és időzítéssel. A shortcuts folyamatban a tipikus alapértelmezett időtartam 5 másodperc.

Utolsó eredmény lekérése

Visszaadja a helyi előzményekből a legutóbbi befejezett eredményt.

Szerver tesztelése

Ellenőrzi a végpont elérhetőségét egy teljes futtatás előtt.

Szerverek listázása

Visszaadja a konfigurált szervereket menüvezérelt automatizáláshoz.

x-callback-url végpontok

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

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

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

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

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

Paraméter	Típus	Kötelező	Leírás
`serverId`	String	Nem	Limit the lookup to one server: `host:port`, a UUID, or `default`. Omit it for the latest result overall.
`serverName`	String	Nem	Same lookup by saved name. Takes precedence over `serverId`.
`format`	String	Nem	`json` (default) or `text`.
`x-success`	String	Nem	Callback URL. Receives `result` with the payload, or `resultRef` when the payload is too large to pass in a URL.
`x-error`	String	Nem	Callback URL. Receives `errorCode` and `errorMessage`.
`x-cancel`	String	Nem	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.

Paraméter	Típus	Kötelező	Leírás
`resultRef`	String	Igen	Reference returned earlier in place of `result`.
`format`	String	Nem	`json` (default) or `text`.
`x-success`	String	Nem	Callback URL. Receives `result` with the payload, or `resultRef` when the payload is too large to pass in a URL.
`x-error`	String	Nem	Callback URL. Receives `errorCode` and `errorMessage`.
`x-cancel`	String	Nem	Callback URL for a cancelled run.

Példák

Teszt futtatása visszahívásokkal

 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 

Legutóbbi eredmény olvasása

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

Terminálindítás macOS-en

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

Tipikus hasznosadat-mezők

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

Hibakezelés

Ha egy művelet sikertelen és az x-error jelen van, a visszahívás egy hibaobjektumot kap.

Kód	Leírás
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"
} 

GYIK

Miért nem tér vissza a visszahívás a Shortcuts alkalmazásba?

Győződj meg arról, hogy a visszahívási URL-ek URL-kódoltak és a séma engedélyezett az eszközödön. Kerüld a szóközöket vagy a kódolatlan szimbólumokat a lekérdezési értékekben.

Tudnak a tesztek teljesen a háttérben futni?

A megbízható végrehajtáshoz tartsd az alkalmazást aktívan a teszt futása alatt. Használj Shortcuts ütemezést a futtatások meghatározott időpontokban való indításához.

Mi a legbiztonságosabb integrációs minta?

Állítsd be az x-error paramétert minden hívásnál, és az errorCode alapján ágazz el. Kezdd rövid, durationSec=5 futással: ha serverNotFound vagy connectionTimeout jön vissza, hosszú tesztet nincs értelme indítani.

Vissza a főoldalra Alkalmazás letöltése