开发者文档

快捷指令与 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 

读取最新结果

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

在 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，再跑长测试没有意义。

返回首页下载应用