Sürekli Sorgular ve Sayfalandırma

Bu kılavuz Agent Java SDK v0.3.0, Java 8+ ve etiketli kamu sözleşmesini hedefler. Örnekler, client başlatıldıktan sonra bir iş ortağı arka ucunda çalıştırılır. Hızlı Başlangıç.

Örnek önkoşullar

Java parçacıkları bu içe aktarmaları paylaşır. Hızlı Başlangıç’ı kullanarak client’ı başlatın ve kaydedilen bağlamadan platformUserId’i edinin. Örnek kullanıcı/sipariş kimlikleri kendi kalıcı değerlerinizle değiştirilmelidir.

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

Kalıcı sözleşme verilerini sorgulama

Altı tür arayüz ve Java yöntemleri

Tüm istekler, ortak bir /v1/agent/perpetual önekiyle POST imzalanır.

platformUserIds genel platform kimliklerinden oluşan bir dize dizisidir. Belirtildiğinde, erişimi olan 1 ila 100 benzersiz oyuncu gereklidir; ihmale izin veren uç noktalarda, yalnızca mevcut satıcının erişebildiği doğrudan oynatıcıların aralığı sorgulanır. Takas doldurma sorguları her zaman bu diziyi gerektirir; koşullu sıralı sorgular ayrıca açık kullanıcı kimlikleri gerektirir. İhmal etme, [] ile eşdeğer değildir ve boş diziler yasa dışıdır. Kapsam, imzayı atan üye işyeri tarafından belirlenir ve kapsamın genişletilmesi için diğer üye işyeri kimlikleri aktarılamaz.

Dizi değerleri, imzalama yüküne katılmadan önce kompakt JSON olarak serileştirilir. Örneğin, platformUserIds, ["1188041528"] olarak işaretler ve k=v yükünde platformUserIds=["1188041528"] verir. Dizi öğesi sırasını, çift tırnakları ve dize kimliklerini koruyun; biçimlendirme boşlukları eklemeyin veya Java List.toString() ([1188041528] gibi) kullanmayın. SDK bu serileştirmeyi otomatik olarak gerçekleştirir.

Sipariş sorgusu orderCategory=NORMAL veya CONDITIONAL’i geçmelidir. Sıradan siparişler için orderId ve koşullu siparişler için conditionId kullanın. Kategoriler arasında karıştırılamazlar. Koşullu emirler ve bunların tetiklenmesiyle oluşan olağan emirler ayrı ayrı varlık olarak işlenir.

Filtre koşulları

Geçmiş sorgunun süresi Unix milisaniye ve aralık [startTime, endTime)’dır; imza isteme süresi timestamp Unix saniyedir. Segmentlerdeki UTC zaman aralığının ve sorgunun düzeltilmesi önerilir; Günlük mutabakat için UTC kullanın. Durum ve tür, platform sözleşme numaralandırmasını kullanır ve kendi başlarına Çince dizelere çevrilmez.

limit Varsayılan 500’dür, aralık 1~1000’dir; sayfa boyutu her seferinde aynı sayının döndürüleceğini garanti etmez. Altı arayüz şu anda saniyede 2 kez ve satıcı başına 4 patlamadan oluşan bir sorgu kotasını paylaşmaktadır ve örnek içindeki her satıcı için maksimum eşzamanlılık sınırı 2’dir. Satıcı tarafı birleştirilmiş bir kuyruk kullanır ve sıralı sayfalama ve daha küçük bir geçmiş penceresiyle başlanması önerilir.

Java sorgu örnekleri

Bir oyuncunun mevcut olağan sırasını sorgulayın:

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

Son saatteki sözleşme değişikliklerini sorgulayın ve imleci işleyin. Aşağıdaki örnek otomatik olarak yeniden denenmez; gerçek uygulama mevcut sınırlamayla veya geçici arızayla karşılaştığında, aynı sayfayı geri yüklemek için bağlantılı ilgili kılavuzu izleyin.

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.
}

İade yapısı ve kaydetme kuralları

Görmek Ortak yanıt ve sayfalandırma Paylaşılan alanlar için. Kaynak alanları şurada belgelenmiştir: Siparişler, Ticaret doluyor, Pozisyonlar Ve Sözleşme defteri.

Altı arayüz aynı şekilde PerpetualResponse değerini döndürür:

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

Her items, platformUserId, entityType, entityId, data içerir. Varlık türleri arasında ORDER, CONDITION_ORDER, TRADE_FILL, POSITION, ACCOUNT_LEDGER bulunur. İdempotent bir anahtar oluşturmak için bu üç kimlik alanını kullanın; koşullu sipariş kimliğini, sipariş kimliğini ve dolum kimliğini aynı numara olarak değerlendirmeyin.

data Kaynağa göre fiyat, miktar, durum, gider, kar ve zarar veya bakiye değişikliği gibi alanlar sağlar. Tutar, fiyat, miktar ve varlık kimliği dizeler olarak işlenir; iş süresi milisaniye cinsindendir. Eksik alanlar 0’a kadar doldurulmaz ve diğer varlıklardan çıkarım yapılmaz.

İmleç, bir sorgunun sayfalama konumudur; güvenilir bir artımlı abonelik veya garantili bir sayfalar arası atomik anlık görüntü değildir. Geçerli imleç, ilk oluşturma turundan itibaren 24 saat boyunca geçerlidir; sonraki sayfalama aynı satıcıları, kaynakları, oyuncu koleksiyonlarını ve filtre koşullarını korur. Geçmiş çekme için sabit pencere tekrar tekrar çekildiğinde önemsizdir; Mevcut emir/pozisyonun durumu yeniden sorgulama sonrasında yenilenir. Gerçek zamanlı bir arayüze ihtiyaç duyulduğunda, platformun ön ucunun veri mekanizması kullanılır ve oylama altı arayüzü, yüksek frekanslı bir piyasa arayüzü olarak kabul edilemez.

Hatalar ve kurtarma

HTTP başarısı iş başarısı anlamına gelmez; code’ı kontrol etmelisiniz. Java SDK, AgentApiException olarak bir iş hatası oluşturacaktır.

Orijinal başarısız sayfanın cursor ve tüm filtre koşulları, mevcut sınırlama, zaman aşımı veya geçici arızadan sonra korunacaktır; SDK her yeniden çağrıldığında, yeni timestamp, nonce, sign oluşturulacaktır. Doğrudan bir sonraki sayfaya atlayamazsınız ve başarısızlıkları boş sonuçlar olarak değerlendiremezsiniz. SDK, fon işlemlerinin otomatik olarak yeniden denenmesinden sorumlu değildir.

Ortak yanıt ve sayfalandırma

Her data.items[]’in yapısı:

Aynı ledgerId, işlem ücretleri, kar ve zarar vb. gibi birden fazla ayrıntıyı ayırabilir; kopyaları kaldırmak için ledgerId tuşuna basmak veri kaybına neden olacaktır. Farklı kaynaklardan gelen kimlikler karıştırılamaz. Sayfalama ve alan kaydetme kuralları için Erişim Kılavuzu’nun bağlantılı ilgili kılavuzuna bakın.

Türler, birimler ve ihmal edilen alanlar

• Tutar, fiyat, miktar ve varlık kimliği kullanım dizesi; miktarları işlemek için ondalık sayıyı kullanın ve kayan noktalı sayıları kullanamaz veya uzun kimlikleri JavaScript Numaralarına dönüştüremez. Tutar para birimi ve miktar birimi, işlem çifti/sözleşme spesifikasyonlarına göre açıklanır.
• İş zamanı tamsayıyı (int64) kullanır; her ikisi de Unix milisaniyedir; kimlik doğrulama zaman damgası isteği ve giriş kimlik bilgileri expireAt saniyeleri kullanır ve karıştırılamaz.
• Dize iş alanları genellikle boş olduklarında çıktılanmaz ve sayısal alanlar 0 olduğunda bazıları atlanır. Eksik alan, iş değerinin 0 olduğu anlamına gelmez.
• Genel kayıt modelinde reduceOnly, closeOnly, makerOnly, false’u atlamaz, dolayısıyla bu üç false, işlemlerde veya pozisyonlarda da görünebilir. Bunlar yalnızca sipariş kaynaklarında açıklanmaktadır; işlemin/pozisyonun ilgili emir kurallarını yerine getirdiği düşünülemez.
• closePosition isteğe bağlı bir boole değeridir: koşullu emirlerle sağlanır, genellikle diğer kaynaklar için atlanır. Eksikliğin yanlıştan farklı bir anlamı vardır.
• Aşağıdaki “şu anda sağlanan” tablo, okuma mantığının bir alan kaynağına sahip olduğu anlamına gelir; isteğe bağlı alanlar, değerleri olmadığından yine de atlanabilir. Modelde bulunan alanların her arayüzde doldurulması garanti edilmez.

Durum ve kenar boşluğu modu arasındaki fark

Sıradan bir sipariş için CANCELED yazımı, koşullu bir sipariş için CANCELLED yazımından farklıdır; Koşullu bir emrin tetiklenmesi, oluşturulan olağan emrin yerine getirildiği anlamına gelmez. Tüm kaynaklar için aynı durum çeviri tabloları kümesini yeniden kullanmayın.

Koşullu sipariş marginMode, CROSS / ISOLATED değerini döndürür; tarihsel olağan emirler ve pozisyonlar şu anda sırasıyla çapraz/izole marj olan “1” / “2” değerini döndürmektedir. marginMode şu anda sıradan siparişler için mevcut değil. Satıcılar kendi görüntüleme katmanlarında kaynağa göre normalleştirme yapabilirler ve orijinal değerlerin yine de kaydedilmesi gerekir.

Modelde bildirilen ancak bu sorguda sağlanmayan alanlar

Generic RecordData / Java PerpetualData modeli ayrıca aşağıdaki alanları da bildirir, ancak mevcut altı kategorili üretim okuma mantığı bunları doldurmaz. **Mevcut iş verileri olarak listelenmemeli veya alan varsayılanları gerçek sonuçların yerine kullanılmamalıdır. **

Gerçek saha uygulama kapsamı yukarıdaki kaynak tablolarına tabidir; Platform, alanları veya numaralandırmaları güncellediğinde, yeni arayüz açıklamasına ve SDK sürümüne göre uyarlanacaktır.

Kaynak ve ilgili kılavuzlar

• Resmi v0.3.0 kaynağı
• Finansman cüzdanı
• Yükseltme kılavuzu