وثائق المطوّرين

Shortcuts وx-callback-url

أتمتة فحوصات الإنتاجية والتحقق من نقاط النهاية وجمع النتائج بإجراءات مدمجة ونقاط نهاية استدعاء.

نظرة عامة

يوفر تطبيق iPerf3 Client & Server طبقتين للأتمتة:

إجراءات 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

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 

التشغيل من Terminal على 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"
} 

الأسئلة الشائعة

لماذا لا يعود استدعائي إلى Shortcuts؟

تأكد من أن URLs الاستدعاء مشفّرة بـ URL وأن المخطط مسموح به على جهازك. تجنّب المسافات أو الرموز غير المُهرَّبة في قيم الاستعلام.

هل يمكن تشغيل الاختبارات في الخلفية كلياً؟

للتنفيذ الموثوق، ابقِ التطبيق نشطاً أثناء تشغيل الاختبار. استخدم جدولة Shortcuts لتشغيل الاختبارات في أوقات محددة.

ما أفضل نمط تكامل؟

حدِّد x-error في كل استدعاء وتفرَّع حسب errorCode. ابدأ بتشغيل قصير durationSec=5: إذا عاد serverNotFound أو connectionTimeout فلا فائدة من اختبار طويل.

العودة إلى الرئيسية تحميل التطبيق