开发者文档

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

读取最新结果

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

在 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，仅在端点检查成功后再运行吞吐量测试。

返回首页下载应用