Dokumentacja dla deweloperów

Shortcuts i x-callback-url

Automatyzuj sprawdzanie przepustowości, walidację punktów końcowych i zbieranie wyników za pomocą wbudowanych akcji i punktów końcowych wywołań zwrotnych.

Przegląd

iPerf3 Client & Server udostępnia dwie warstwy automatyzacji:

Natywne akcje Apple Shortcuts (zalecane dla większości użytkowników)
Punkty końcowe x-callback-url dla skryptowalnych przepływów pracy między aplikacjami

Podstawowy schemat URL

Używaj iperf3cs://x-callback-url/... dla automatyzacji opartej na wywołaniach zwrotnych.

Zgodność

Aktualne wymagania platformy Apple to iOS/iPadOS 16.6+, macOS 13.5+ i visionOS 1.0+.

Wbudowane akcje Shortcuts

Te akcje są dostępne bezpośrednio w aplikacji Apple Shortcuts:

Uruchom test iPerf

Uruchamia test z konfigurowalnym serwerem, protokołem, kierunkiem i czasem. Typowy domyślny czas trwania w przepływie shortcuts wynosi 5 sekund.

Pobierz ostatni wynik

Zwraca najnowszy ukończony wynik z lokalnej historii.

Sprawdź serwer

Sprawdza dostępność punktu końcowego przed pełnym uruchomieniem.

Lista serwerów

Zwraca skonfigurowane serwery dla automatyzacji sterowanej menu.

Punkty końcowe x-callback-url

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

Uruchamia nowy test i opcjonalnie zwraca wyniki przez adresy URL wywołania zwrotnego.

Parametr	Typ	Wymagany	Opis
`server`	String	Tak	Nazwa hosta lub IP punktu końcowego iPerf3.
`protocol`	String	Nie	`tcp` (domyślnie) lub `udp`.
`direction`	String	Nie	`download`, `upload` lub `bidirectional`.
`durationSec`	Integer	Nie	Czas trwania w sekundach. Typowa wartość domyślna w automatyzacji to 5.
`streams`	Integer	Nie	Liczba równoległych strumieni.
`x-success`	String	Nie	Adres URL wywołania zwrotnego dla ładunku wyniku sukcesu.
`x-error`	String	Nie	Adres URL wywołania zwrotnego dla ładunku błędu.

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

Zwraca najnowszy lokalny wynik, przydatny dla cyklicznych przepływów pracy logowania.

Parametr	Typ	Wymagany	Opis
`x-success`	String	Nie	Adres URL wywołania zwrotnego dla pomyślnego ładunku.
`x-error`	String	Nie	Adres URL wywołania zwrotnego dla błędów.

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

Sprawdza osiągalność punktu końcowego i zwraca metadane statusu/opóźnienia.

Parametr	Typ	Wymagany	Opis
`server`	String	Tak	Nazwa hosta lub IP do sprawdzenia.
`port`	Integer	Nie	Wartość portu (domyślnie 5201).

Przykłady

Uruchom test z wywołaniami zwrotnymi

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

Odczytaj najnowszy wynik

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

Uruchomienie z terminala na macOS

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

Typowe pola ładunku

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

Obsługa błędów

Gdy akcja zawiedzie i obecny jest x-error, wywołanie zwrotne otrzymuje obiekt błędu.

Kod	Opis
ERR_CONNECTION_FAILED	Nie można połączyć się z punktem końcowym.
ERR_TIMEOUT	Połączenie lub test przekroczyły limit czasu.
ERR_INVALID_SERVER	Nieprawidłowy host lub nieosiągalny adres.
ERR_NO_RESULTS	Brak zapisanych wyników dla żądanej akcji.
ERR_INVALID_PARAMS	Brakujące lub nieprawidłowe wymagane parametry.

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

FAQ

Dlaczego moje wywołanie zwrotne nie wraca do Shortcuts?

Upewnij się, że adresy URL wywołania zwrotnego są zakodowane w URL, a schemat jest dozwolony na Twoim urządzeniu. Unikaj spacji lub niezakodowanych znaków specjalnych w wartościach zapytań.

Czy testy mogą działać całkowicie w tle?

Dla niezawodnego działania utrzymuj aplikację aktywną podczas trwania testu. Używaj planowania Shortcuts, aby wyzwalać uruchomienia o określonych porach.

Jaki jest najbezpieczniejszy wzorzec integracji?

Użyj najpierw test-server, a następnie uruchom test przepustowości tylko jeśli sprawdzenie punktu końcowego zakończy się sukcesem.

Powrót do strony głównej Pobierz aplikację