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

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

يبدأ اختباراً جديداً ويُرجع اختيارياً عبر URLs الاستدعاء.

المعامل	النوع	مطلوب	الوصف
`server`	String	نعم	اسم المضيف أو عنوان IP لنقطة نهاية iPerf3.
`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 

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

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

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

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

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

استخدم test-server أولاً، ثم شغّل اختبار الإنتاجية فقط إذا نجح فحص نقطة النهاية.

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