الاستعلامات الدائمة وترقيم الصفحات

يستهدف هذا الدليل Agent Java SDK v0.3.0، Java 8+، والعقد العام الموسوم. يتم تشغيل الأمثلة في الواجهة الخلفية للشريك بعد تهيئة client في بداية سريعة.

مثال المتطلبات الأساسية

تشترك مقتطفات Java في هذه الواردات. قم بتهيئة client باستخدام البدء السريع واحصل على platformUserId من الرابط المحفوظ. يجب استبدال معرفات المستخدم/الطلب بالقيم الثابتة الخاصة بك.

import com.sixmm.agent.*;
import com.sixmm.agent.model.*;
import java.util.*;

الاستعلام عن بيانات العقد الدائم

ستة أنواع من الواجهات وطرق Java

يتم توقيع جميع الطلبات POST ببادئة مشتركة هي /v1/agent/perpetual.

platformUserIds عبارة عن مجموعة من معرفات النظام الأساسي العام. عند التحديد، يلزم وجود من 1 إلى 100 لاعب فريد لديهم حق الوصول؛ في نقاط النهاية التي تسمح بالإغفال، يتم الاستعلام فقط عن نطاق اللاعبين المباشرين الذين يمكن للتاجر الحالي الوصول إليهم. تتطلب استعلامات تعبئة التجارة دائمًا هذه المصفوفة؛ تتطلب استعلامات الترتيب الشرطي أيضًا معرفات مستخدم صريحة. الإغفال لا يعادل []، والمصفوفات الفارغة غير قانونية. يتم تحديد النطاق بواسطة التاجر الموقّع، ولا يمكن تمرير معرفات التجار الأخرى لتوسيع النطاق.

يتم تسلسل قيم المصفوفة على أنها مضغوطة JSON قبل الانضمام إلى حمولة التوقيع. على سبيل المثال، يشير platformUserIds إلى ["1188041528"]، مما يؤدي إلى ظهور platformUserIds=["1188041528"] في الحمولة النافعة k=v. الحفاظ على ترتيب عناصر المصفوفة وعلامات الاقتباس المزدوجة ومعرفات السلسلة؛ لا تقم بإدخال مسافات التنسيق أو استخدام Java List.toString() (مثل [1188041528]). يعالج SDK هذا التسلسل تلقائيًا.

يجب أن يمر استعلام الطلب orderCategory=NORMAL أو CONDITIONAL. استخدم orderId للأوامر العادية وconditionId للأوامر المشروطة. ولا يمكن الخلط بينها عبر الفئات. تتم معالجة الأوامر المشروطة والأوامر العادية الناتجة عن تشغيلها بشكل منفصل ككيانات.

شروط التصفية

وقت الاستعلام التاريخي هو Unix ملي ثانية، والفاصل الزمني هو [startTime, endTime)؛ وقت طلب التوقيع هو timestamp هو يونكس ثانية. يوصى بإصلاح نافذة الوقت والاستعلام UTC في المقاطع؛ استخدم UTC للتسوية اليومية. تستخدم الحالة والنوع تعداد عقد المنصة ولا تتم ترجمتهما إلى سلاسل صينية من تلقاء نفسها.

limit الافتراضي هو 500، النطاق هو 1 ~ 1000؛ لا يضمن حجم الصفحة إرجاع نفس الرقم في كل مرة. تشترك الواجهات الستة حاليًا في حصة استعلام تبلغ مرتين في الثانية و4 دفعات لكل تاجر، والحد الأقصى للتزامن لكل تاجر داخل المثيل هو 2. يستخدم جانب التاجر قائمة انتظار موحدة، ومن المستحسن البدء بالترحيل المتسلسل ونافذة سجل أصغر.

Java أمثلة الاستعلام

الاستعلام عن الترتيب العادي الحالي للاعب:

CurrentPerpetualOrdersRequest current = new CurrentPerpetualOrdersRequest();
current.orderCategory = "NORMAL";
current.platformUserIds = Collections.singletonList(platformUserId);
current.symbol = "BTCUSDT";
current.limit = 100;
PerpetualResponse currentPage = client.listCurrentPerpetualOrders(current);

الاستعلام عن تغييرات العقد في الساعة الأخيرة ومعالجة المؤشر. المثال التالي لا يقوم بإعادة المحاولة تلقائياً؛ عندما يواجه التطبيق الفعلي قيودًا حالية أو فشلًا مؤقتًا، اتبع الدليل المرتبط ذي الصلة لاستعادة نفس الصفحة.

PerpetualLedgerRequest ledger = new PerpetualLedgerRequest();
ledger.platformUserIds = Collections.singletonList(platformUserId);
ledger.endTime = System.currentTimeMillis();
ledger.startTime = ledger.endTime - 3_600_000L;
ledger.limit = 100;
Set<String> seenCursors = new HashSet<>();
while (true) {
    PerpetualResponse page = client.listPerpetualLedger(ledger);
    for (PerpetualRecord row : page.data.items) {
        // Persist records idempotently by platformUserId, entityType and entityId.
    }
    if (!page.data.hasMore) {
        break;
    }
    String next = page.data.nextCursor;
    if (next == null || next.isEmpty() || !seenCursors.add(next)) {
        throw new IllegalStateException("游标未推进，停止查询并排查");
    }
    ledger.cursor = next;
    Thread.sleep(650L); // Other queries must share the same partner rate-limit queue.
}

هيكل العودة وقواعد الحفظ

يرى الاستجابة المشتركة وترقيم الصفحات للحقول المشتركة. تم توثيق حقول الموارد في طلبات, يملأ التجارة, المواقف و دفتر العقود.

تقوم الواجهات الستة بإرجاع PerpetualResponse بشكل موحد:

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [],
    "nextCursor": "",
    "hasMore": false
  }
}

يحتوي كل items على platformUserId، entityType، entityId، data. تتضمن أنواع الكيانات ORDER، CONDITION_ORDER، TRADE_FILL، POSITION، ACCOUNT_LEDGER. استخدم حقول الهوية الثلاثة هذه لإنشاء مفتاح غير فعال؛ لا تتعامل مع معرف الطلب المشروط ومعرف الطلب ومعرف التعبئة بنفس الرقم.

data يوفر حقول مثل السعر أو الكمية أو الحالة أو النفقات أو الربح والخسارة أو تغيير الرصيد حسب المورد. يتم التعامل مع المبلغ والسعر والكمية ومعرف الكيان كسلاسل؛ وقت العمل بالمللي ثانية. لا يتم ملء الحقول المفقودة إلى 0 ولا يتم استنتاجها من الكيانات الأخرى.

المؤشر هو موضع الترحيل للاستعلام، وليس اشتراكًا تزايديًا موثوقًا به، ولا لقطة ذرية مضمونة عبر الصفحات. المؤشر الحالي صالح لمدة 24 ساعة من الجولة الأولى من الجيل؛ تحتفظ الترحيل اللاحق بنفس التجار والموارد ومجموعات اللاعبين وشروط التصفية. النافذة الثابتة للسحب التاريخي تصبح عاجزة عند سحبها بشكل متكرر؛ يتم تحديث حالة الطلب/الموضع الحالي بعد إعادة الاستعلام. عندما تكون هناك حاجة إلى واجهة في الوقت الفعلي، يتم استخدام آلية البيانات الخاصة بالواجهة الأمامية للنظام الأساسي، ولا يمكن اعتبار واجهة الاقتراع الستة بمثابة واجهة سوق عالية التردد.

الأخطاء والاسترداد

HTTP النجاح لا يعني نجاح الأعمال، يجب عليك التحقق من code. Java SDK سوف يؤدي إلى حدوث خطأ تجاري كـ AgentApiException.

سيتم الاحتفاظ بـ cursor وجميع شروط التصفية الخاصة بالصفحة الفاشلة الأصلية بعد التقييد الحالي أو انتهاء المهلة أو الفشل المؤقت؛ في كل مرة تتم إعادة استدعاء SDK، سيتم إنشاء timestamp، nonce، sign جديدة. لا يمكنك الانتقال مباشرة إلى الصفحة التالية، ولا يمكنك التعامل مع حالات الفشل على أنها نتائج فارغة. SDK ليس مسؤولاً عن إعادة محاولة المعاملات المالية تلقائيًا.

الاستجابة المشتركة وترقيم الصفحات

هيكل كل data.items[]:

يمكن لنفس ledgerId فصل تفاصيل متعددة مثل رسوم المناولة والأرباح والخسائر وما إلى ذلك؛ سيؤدي الضغط على ledgerId لإزالة التكرارات إلى فقدان البيانات. لا يمكن خلط المعرفات من موارد مختلفة. راجع الدليل المرتبط بدليل الوصول للتعرف على قواعد حفظ الصفحات وحفظ الحقول.

الأنواع والوحدات والحقول المحذوفة

• يستخدم المبلغ والسعر والكمية ومعرف الكيان؛ استخدم العلامة العشرية لمعالجة المبالغ، ولا يمكن استخدام أرقام الفاصلة العائمة أو تحويل المعرفات الطويلة إلى أرقام JavaScript. يتم شرح عملة المبلغ ووحدة الكمية وفقًا لمواصفات زوج التداول/العقد.
• يستخدم وقت العمل عددًا صحيحًا (int64)، وكلاهما ميلي ثانية من Unix؛ يستخدم الطابع الزمني للمصادقة وبيانات اعتماد الإدخال expireAt الثواني ولا يمكن الخلط بينها.
• عادةً لا يتم إخراج حقول الأعمال المتسلسلة عندما تكون فارغة، وسيتم حذف بعضها عندما تكون الحقول الرقمية 0. لا يعني الحقل المفقود أن قيمة الأعمال هي 0.
• reduceOnly، closeOnly، makerOnly في نموذج السجل العام لا تحذف خطأ، لذلك قد تظهر هذه الأخطاء الثلاثة أيضًا في المعاملات أو المراكز. يتم شرحها فقط في موارد الطلب؛ لا يمكن اعتبار أن المعاملة/المركز نفذ قواعد الأمر المقابلة.
• closePosition هو قيمة منطقية اختيارية: يتم توفيرها بواسطة أوامر مشروطة، ويتم حذفها عادةً للموارد الأخرى. المفقود له معنى مختلف عن الكذب.
• الجدول أدناه “المقدم حاليًا” يعني أن منطق القراءة له مصدر حقل؛ من الممكن أن يتم حذف الحقول الاختيارية لأنها لا تحتوي على قيمة. لا يمكن ضمان ملء الحقول الموجودة في النموذج في كل واجهة.

الفرق بين الحالة ووضع الهامش

يختلف تهجئة CANCELED للأمر العادي عن تهجئة CANCELLED للأمر الشرطي؛ إن إطلاق أمر مشروط لا يعني أن الأمر العادي الذي تم إنشاؤه قد تم تنفيذه. لا تقم بإعادة استخدام نفس مجموعة جداول ترجمة الحالة لجميع الموارد.

الترتيب الشرطي marginMode يُرجع CROSS / ISOLATED; تُرجع الأوامر والصفقات العادية التاريخية حاليًا “1” / “2”، وهي عبارة عن هامش متقاطع/معزول على التوالي. marginMode غير متوفر حاليًا للطلبات العادية. يمكن للتجار التطبيع حسب المورد في طبقة العرض الخاصة بهم، ولا تزال القيم الأصلية بحاجة إلى حفظها.

الحقول المعلنة في النموذج ولكنها غير متوفرة في هذا الاستعلام

Generic RecordData / Java يعلن نموذج PerpetualData أيضًا عن الحقول التالية، لكن منطق قراءة الإنتاج الحالي المكون من ست فئات لا يملأها. **لا ينبغي إدراجها كبيانات أعمال متاحة، ولا ينبغي استبدال الإعدادات الافتراضية للحقول بنتائج حقيقية. **

يخضع نطاق التطبيق الميداني الفعلي لجداول الموارد المذكورة أعلاه؛ عندما تقوم المنصة بتحديث الحقول أو التعدادات، يجب تكييفها وفقًا لوصف الواجهة الجديدة وإصدار SDK.

المصدر والأدلة ذات الصلة

• المصدر الرسمي v0.3.0
• محفظة التمويل
• دليل الترقية