개발자 문서

단축어 및 x-callback-url

내장된 작업과 콜백 엔드포인트로 처리량 검사, 엔드포인트 검증 및 결과 수집을 자동화하십시오.

개요

iPerf3 Client & Server는 두 가지 자동화 레이어를 제공합니다:

네이티브 Apple 단축어 작업 (대부분의 사용자에게 권장)
스크립터블 앱 간 워크플로를 위한 x-callback-url 엔드포인트

기본 URL 체계

콜백 기반 자동화에는 iperf3cs://x-callback-url/...을 사용하십시오.

호환성

현재 Apple 플랫폼 요구 사항은 iOS/iPadOS 16.6+, macOS 13.5+ 및 visionOS 1.0+입니다.

내장 단축어 작업

이 작업들은 Apple 단축어 앱에서 직접 사용할 수 있습니다:

iPerf 테스트 실행

구성 가능한 서버, 프로토콜, 방향 및 타이밍으로 테스트를 실행합니다. 단축어 흐름의 일반적인 기본 지속 시간은 5초입니다.

마지막 결과 가져오기

로컬 기록에서 가장 최근에 완료된 결과를 반환합니다.

서버 테스트

전체 실행 전에 엔드포인트 가용성을 확인합니다.

서버 목록

메뉴 기반 자동화를 위해 구성된 서버를 반환합니다.

x-callback-url 엔드포인트

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

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

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

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

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

파라미터	유형	필수	설명
`serverId`	String	아니오	Limit the lookup to one server: `host:port`, a UUID, or `default`. Omit it for the latest result overall.
`serverName`	String	아니오	Same lookup by saved name. Takes precedence over `serverId`.
`format`	String	아니오	`json` (default) or `text`.
`x-success`	String	아니오	Callback URL. Receives `result` with the payload, or `resultRef` when the payload is too large to pass in a URL.
`x-error`	String	아니오	Callback URL. Receives `errorCode` and `errorMessage`.
`x-cancel`	String	아니오	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.

파라미터	유형	필수	설명
`resultRef`	String	예	Reference returned earlier in place of `result`.
`format`	String	아니오	`json` (default) or `text`.
`x-success`	String	아니오	Callback URL. Receives `result` with the payload, or `resultRef` when the payload is too large to pass in a URL.
`x-error`	String	아니오	Callback URL. Receives `errorCode` and `errorMessage`.
`x-cancel`	String	아니오	Callback URL for a cancelled run.

예시

콜백으로 테스트 실행

 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 

macOS에서 터미널 시작

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

일반적인 페이로드 필드

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

오류 처리

작업이 실패하고 x-error가 있는 경우, 콜백은 오류 객체를 받습니다.

코드	설명
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"
} 

자주 묻는 질문

콜백이 단축어로 돌아오지 않는 이유는 무엇입니까?

콜백 URL이 URL 인코딩되어 있고 체계가 기기에서 허용되는지 확인하십시오. 쿼리 값에 공백이나 이스케이프되지 않은 기호를 사용하지 마십시오.

테스트가 완전히 백그라운드에서 실행될 수 있습니까?

신뢰할 수 있는 실행을 위해 테스트 런타임 동안 앱을 활성 상태로 유지하십시오. 단축어 예약을 사용하여 특정 시간에 실행을 트리거하십시오.

가장 안전한 통합 패턴은 무엇입니까?

모든 호출에 x-error를 지정하고 errorCode로 분기하십시오. durationSec=5의 짧은 실행부터 시작하고, serverNotFound나 connectionTimeout이 돌아오면 긴 테스트는 의미가 없습니다.

홈으로 돌아가기 앱 다운로드