التوثيق
حداثة البيانات
يخزّن Narwhal الإصدارات الرسمية المقبولة ثم يقدّمها دون استدعاء المصدر أثناء طلب API الخاص بك.
تعني كلمة حديث أحدث إصدار رسمي كامل تحققت منه Narwhal ونشرته. ولا تعني أن كل طلب عميل يستدعي المصدر الرسمي مباشرةً.
مصدر الاستجابات
يقرأ كل طلب REST أو MCP ناجح الإصدار الحالي المخزن لدى Narwhal. ويفحص نظام الاستيعاب مواقع المصدر وملفاته وواجهاته بشكل منفصل.
هذا يجعل زمن استجابة العميل مستقلاً عن سرعة المصدر الرسمي أو انقطاعه المؤقت.
كيفية تحديث الإصدارات
- يفحص عامل مجدول المصدر الرسمي بحثًا عن إصدار جديد.
- يسترجع Narwhal مادة المصدر ويتحقق من هويتها وفترتها وحقولها واكتمالها.
- تُخزّن القراءات الموحّدة الصيغة والأدلة الداعمة معًا.
- بعد اجتياز الإصدار الكامل التحقق فقط، يجعله Narwhal النسخة التي يعيدها للعملاء.
لا يُمزج المرشح غير المكتمل أو غير الصالح أبدًا في الاستجابة العامة.
معنى حقول حداثة البيانات
| حقل أو إشارة | المعنى |
|---|---|
period | الشهر أو الربع أو السنة التي تمثلها القراءة الرسمية. |
released_on | تاريخ النشر الرسمي. ليس وقت استرجاع Narwhal أو وقت نشره. |
as_of | في استجابات السجل، وقت آخر تحديث من المصدر لأحدث رصد في الصفحة، بالثواني الكاملة وبتوقيت UTC. |
observed_at | لإصدار تقويم واحد، الوقت الذي رصدته فيه Narwhal آخر مرة في تقويم الناشر. |
timestamp, market_session | لـFX والأسعار الفورية، وقت UTC الذي ينتمي إليه السعر. ولـFX، حالة السوق أيضًا. |
| طلب أحدث إصدار | حذف period يطلب أحدث إصدار كامل مقبول مخزن حالياً لدى Narwhal. |
| طلب لفترة محددة | تمرير period يطلب تلك الفترة المنشورة الدقيقة عندما تظل متاحة في الإصدار الرسمي الحالي. |
stale | تحمل استجابات أسعار السلع الفورية وFX وأحداث التنبؤات stale. بالنسبة إلى الأسعار الفورية وFX، تعني stale: true أن القيمة قديمة أثناء فتح سوقها: إما أن مصدرها يشير إلى أنها قديمة، أو أن عمرها تجاوز 10 دقائق، مع احتساب وقت فتح السوق فقط. إغلاق السوق وحده لا يجعل قيمة الأسعار الفورية أو FX قديمة. تُعد أحداث التنبؤات القادمة والجاري تداولها قديمة بعد مرور 3 دقائق دون التحقق لدى منصة التداول؛ راجع مرجع التنبؤات. القيمة هي آخر قيمة معروفة، ويحدد timestamp وقت تعيينها (وفي أحداث التنبؤات، as_of). |
لا تكشف الاستجابات عن طابع زمني لاستيعاب Narwhal للبيانات سوى الحقول أعلاه. استخدم تقويم الإصدارات الرسمي، واتصل بالدعم مع معرّف الطلب إذا بدا أن إصدارًا معروفًا قد تأخر.
عندما يفشل فحص المصدر
يبقي Narwhal آخر منشور مقبول متاحًا. ولا يمحوه أو يستبدل القيم المفقودة بأصفار أو ينشر تحديثًا جزئيًا.
تُعاد محاولة فحص المصدر الذي فشل وفق جدوله. وإذا لم تتمكن Narwhal من تقديم إصدار مقبول بأمان، يفشل الطلب مع خطأ موثّق برمز 503 بدلًا من إعادة بيانات غير مؤكدة.
توقعات النسخة التجريبية العامة
- لا يَعِد Narwhal خلال المرحلة التجريبية بتأخر ثابت بين المصدر والنشر.
- يقيس زمن استجابة API للعميل قراءة البيانات المخزنة، وليس الوقت اللازم لاستيعاب إصدار رسمي جديد.
- يمكن للوكالات الرسمية مراجعة فترة ما؛ ولذلك قد يستبدل منشور مقبول لاحقًا القيمة المخزنة سابقًا.
- قد تكون الأرقام الاقتصادية الرئيسية التي توفرها نقاط النهاية الأساسية وأدوات MCP في Narwhal API تقديرات أولية غير نهائية، ولا توضح الاستجابة أنها غير نهائية؛ وتحل الأرقام النهائية للمصدر محلها عند نشرها.
تابع باستخدام مرجع واجهة API للاقتصاد أو المراجعة الأخطاء وإعادة المحاولة.