تنزيل البيانات التاريخية

البيانات التاريخية لكل جهاز موجودة في ملفات نصية (datalogs) على خادم الجهاز. يغطي كل ملف يومًا واحدًا أو شهرًا واحدًا أو السجل الكامل. تحتاج إلى إذن القراءة على الجهاز.

للتصدير بدون كود، استخدم تقارير التطبيق. انظر بياناتك (الاحتفاظ، التصدير، الحذف).

الإجراء

1. ابحث عن خادم الجهاز. استدعِ get_device_info.php واقرأ الحقل device_server. انظر REST API.
2. ابحث عن ترتيب الأعمدة. استدعِ get_device_definitions.php?family_id=<family> واقرأ readings وoutput_names.
3. احسب المستوى ورقم الملف (bin) للفترة التي تريدها.
4. نزّل كل ملف من خادم الجهاز.
5. اجمع الصفوف، ورتبها حسب الطابع الزمني، واملأ الحقول الفارغة.

الطلب

curl --compressed \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  "https://DEVICE_SERVER/datalogs.php?serialno=e11:123&id=0.20740&ver=2"

استبدل DEVICE_SERVER بقيمة الحقل device_server للجهاز.

المعامل	القيمة
serialno	الرقم التسلسلي للجهاز
id	<level>.<bin>، مثلًا 0.20740
ver	2

للمصادقة، أرسل الترويسة Authorization: Bearer-API YOUR_API_KEY أو Authorization: Bearer YOUR_ACCESS_TOKEN.

يمكن أن يرسل الخادم الملف مضغوطًا (gzip أو br). يفك خيار curl --compressed الضغط.

رمز HTTP	المعنى
200	الملف، كـ text/plain
400	serialno أو id خاطئ
403	ليس لديك إذن القراءة على الجهاز
404	لا توجد بيانات لهذا الملف

المستويات وأرقام الملفات

كل الحسابات تستخدم UTC.

المستوى	ملف واحد لكل	حساب الـ bin	مثال
0	يوم	floor(unix_seconds / 86400)	14 أكتوبر 2026 = 0.20740
1	شهر	(year - 1970) * 12 + (month - 1)	أكتوبر 2026 = 1.681
2	السجل الكامل	دائمًا m	2.m

يحتوي المستوى 0 على كل صفوف اليوم. يحتوي المستوى 1 على صف واحد تقريبًا لكل يوم. يحتوي المستوى 2 على صف واحد تقريبًا لكل شهر.

يستخدم التطبيق المستوى 0 للفترات حتى 7 أيام والمستوى 1 للفترات حتى 5 أشهر. للفترات الأطول يستخدم 2.m.

نصيحة

لفترة طويلة على المستوى 0 تحتاج إلى طلب واحد لكل يوم. يرسل التطبيق حتى 6 طلبات في الوقت نفسه. افعل الشيء نفسه في برنامجك.

تنسيق الصف

كل صف قياس واحد. تُفصل الحقول بـ ;.

timestamp;reading1;reading2;...;readingN;output1;...;outputM

• timestamp بثواني unix (UTC). يمكن أن يحتوي على كسور عشرية.
• بعده تأتي القراءات، بترتيب readings للعائلة.
• بعدها تأتي المخرجات، بترتيب output_names.
• يعني الحقل الفارغ أن القيمة لم تتغير. استخدم آخر قيمة من صف سابق.
• تعني القيمة 2147483648 أن القراءة مفقودة.
• الصفوف ليست مرتبة دائمًا. رتبها حسب timestamp.

مثال

لجهاز من العائلة e11 القراءات readings = ["T", "GI", "GIC", "GI2", "GI2C"] وليس له مخرجات.

1791936198.977;2120;1;0;1;0

الحقل	القيمة	المعنى
timestamp	1791936198.977	وقت القياس
T	2120	21.20 °C، لأن تحويل T هو divide_by_100
GI	1	حالة المدخل الأول
GIC	0	عداد المدخل الأول
GI2	1	حالة المدخل الثاني
GI2C	0	عداد المدخل الثاني

تجد التحويلات والوحدات في قاموس readings في التعريفات. انظر REST API.

مثال Shell

ينزّل هذا المثال آخر 3 أيام لجهاز.

SERVER=DEVICE_SERVER
SN=e11:123
TODAY=$(( $(date -u +%s) / 86400 ))
for BIN in $(seq $((TODAY - 2)) $TODAY); do
  curl -s --compressed \
    -H "Authorization: Bearer-API YOUR_API_KEY" \
    "https://$SERVER/datalogs.php?serialno=$SN&id=0.$BIN&ver=2"
done | sort -t';' -k1,1n

طريقة أخرى

في خادم MCP الأداة get_device_history. تقبل المستويات والـ bins نفسها.