개발자 문서

단축어 및 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

새 테스트를 시작하고 선택적으로 콜백 URL을 통해 반환합니다.

파라미터	유형	필수	설명
`server`	String	예	iPerf3 엔드포인트의 호스트명 또는 IP.
`protocol`	String	아니오	`tcp` (기본값) 또는 `udp`.
`direction`	String	아니오	`download`, `upload` 또는 `bidirectional`.
`durationSec`	Integer	아니오	초 단위 지속 시간. 자동화의 일반적인 기본값은 5입니다.
`streams`	Integer	아니오	병렬 스트림 수.
`x-success`	String	아니오	성공 결과 페이로드를 위한 콜백 URL.
`x-error`	String	아니오	오류 페이로드를 위한 콜백 URL.

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

가장 최근 로컬 결과를 반환하며, 주기적인 로깅 워크플로에 유용합니다.

파라미터	유형	필수	설명
`x-success`	String	아니오	성공적인 페이로드를 위한 콜백 URL.
`x-error`	String	아니오	오류를 위한 콜백 URL.

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

엔드포인트 접근 가능성을 확인하고 상태/지연 메타데이터를 반환합니다.

파라미터	유형	필수	설명
`server`	String	예	테스트할 호스트명 또는 IP.
`port`	Integer	아니오	포트 값 (기본값 5201).

예시

콜백으로 테스트 실행

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

macOS에서 터미널 시작

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

일반적인 페이로드 필드

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

오류 처리

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

코드	설명
ERR_CONNECTION_FAILED	엔드포인트에 연결할 수 없습니다.
ERR_TIMEOUT	연결 또는 테스트가 타임아웃을 초과했습니다.
ERR_INVALID_SERVER	호스트 형식이 잘못되었거나 주소에 접근할 수 없습니다.
ERR_NO_RESULTS	요청된 작업에 대한 저장된 결과가 없습니다.
ERR_INVALID_PARAMS	필수 파라미터가 누락되었거나 유효하지 않습니다.

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

자주 묻는 질문

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

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

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

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

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

먼저 test-server를 사용하고, 엔드포인트 확인이 성공한 경우에만 처리량 테스트를 실행하십시오.

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