開発者ドキュメント

ShortcutsとX-callback-url

組み込みアクションとコールバックエンドポイントを使用して、スループットチェック、エンドポイント検証、結果収集を自動化。

概要

iPerf3クライアント＆サーバーは2つのオートメーションレイヤーを公開しています：

ネイティブApple Shortcutsアクション（ほとんどのユーザーに推奨）
スクリプタブルなアプリ間ワークフロー用のx-callback-urlエンドポイント

ベースURLスキーム

コールバックベースのオートメーションにはiperf3cs://x-callback-url/...を使用。

互換性

現在のAppleプラットフォーム要件はiOS/iPadOS 16.6以降、macOS 13.5以降、visionOS 1.0以降です。

組み込みShortcutsアクション

これらのアクションはApple Shortcutsアプリで直接利用可能です：

iPerf テストを実行

設定可能なサーバー、プロトコル、方向、タイミングでテストを実行。Shortcutsフローのデフォルト時間は通常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"
} 

よくある質問

コールバックがShortcutsに戻らないのはなぜですか？

コールバックURLがURLエンコードされており、スキームがデバイスで許可されていることを確認してください。クエリ値にスペースやエスケープされていない記号を使用しないでください。

テストをバックグラウンドで完全に実行できますか？

確実な実行のため、テスト実行中はアプリをアクティブな状態に保ってください。Shortcutsのスケジュール機能を使用して特定の時間にテストを起動してください。

最も安全な統合パターンは何ですか？

まずtest-serverを使用し、エンドポイントチェックが成功した場合のみスループットテストを実行してください。

ホームに戻るアプリをダウンロード