Ciągłe zapytania i paginacja

Ten przewodnik jest przeznaczony dla Agent Java SDK v0.3.0, Java 8+ i oznaczonych zamówień publicznych. Przykłady działają w zapleczu partnera po inicjalizacji client w Szybki start.

Przykładowe wymagania wstępne

Fragmenty Java dzielą ten import. Zainicjuj client za pomocą Szybki start i uzyskaj platformUserId z zapisanego powiązania. Przykładowe identyfikatory użytkowników/zamówień należy zastąpić własnymi, utrwalonymi wartościami.

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

Zapytanie o dane dotyczące umowy bezterminowej

Sześć typów interfejsów i metod Java.

Wszystkie żądania są podpisane POST wspólnym prefiksem /v1/agent/perpetual.

platformUserIds to tablica ciągów zawierająca identyfikatory platform publicznych. Jeśli określono, wymaganych jest od 1 do 100 unikalnych graczy mających dostęp; na punktach końcowych, które pozwalają na pominięcie, sprawdzany jest tylko zakres bezpośrednich graczy, do których bieżący sprzedawca ma dostęp. Zapytania wypełniające transakcje zawsze wymagają tej tablicy; zapytania kolejności warunkowej również wymagają jawnych identyfikatorów użytkowników. Pominięcie nie jest równoznaczne z [], a puste tablice są nielegalne. Zakres jest określany przez sprzedawcę podpisującego i nie można przekazać innych identyfikatorów sprzedawców w celu rozszerzenia zakresu.

Wartości tablicy są serializowane jako kompaktowe JSON przed dołączeniem do ładunku podpisującego. Na przykład platformUserIds znakuje jako ["1188041528"], podając platformUserIds=["1188041528"] w ładunku k=v. Zachowaj kolejność elementów tablicy, podwójne cudzysłowy i identyfikatory ciągów; nie wstawiaj spacji formatujących ani nie używaj Java List.toString() (np. [1188041528]). SDK automatycznie obsługuje tę serializację.

Zapytanie o zamówienie musi przejść orderCategory=NORMAL lub CONDITIONAL. Użyj orderId dla zleceń zwykłych i conditionId dla zleceń warunkowych. Nie można ich mieszać w różnych kategoriach. Zlecenia warunkowe oraz zlecenia zwykłe generowane w wyniku ich uruchomienia przetwarzane są oddzielnie jako byty.

Warunki filtra

Czas zapytania historycznego to Unix milisekundy, a interwał to [startTime, endTime); czas żądania podpisu to timestamp to Unix sekund. Zalecane jest naprawienie okna czasowego UTC i zapytanie w segmentach; używaj UTC do codziennego pojednania. Status i typ korzystają z wyliczenia umów platformy i nie są same w sobie tłumaczone na chińskie ciągi znaków.

limit Wartość domyślna to 500, zakres to 1~1000; rozmiar strony nie gwarantuje, że za każdym razem zostanie zwrócona ta sama liczba. Sześć interfejsów ma obecnie wspólny limit zapytań wynoszący 2 razy na sekundę i 4 serie na sprzedawcę, a maksymalny limit współbieżności dla każdego sprzedawcy w instancji wynosi 2. Strona sprzedawcy korzysta z ujednoliconej kolejki i zaleca się rozpoczęcie od stronicowania sekwencyjnego i mniejszego okna historii.

Java przykłady zapytań

Zapytaj o bieżący zwyczajny porządek gracza:

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

Zapytaj o zmiany w umowie w ciągu ostatniej godziny i przetwórz kursor. Poniższy przykład nie powoduje automatycznego ponawiania próby; gdy rzeczywista aplikacja napotka bieżące ograniczenie lub tymczasową awarię, postępuj zgodnie z powiązanym przewodnikiem, aby przywrócić tę samą stronę.

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

Struktura zwrotów i zasady zapisywania

Widzieć Wspólna odpowiedź i paginacja dla wspólnych pól. Pola zasobów są udokumentowane w Święcenia, Handel wypełnia, Pozycje I Księga kontraktowa.

Sześć interfejsów równomiernie zwraca PerpetualResponse:

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

Każde items zawiera platformUserId, entityType, entityId, data. Typy jednostek obejmują ORDER, CONDITION_ORDER, TRADE_FILL, POSITION, ACCOUNT_LEDGER. Użyj tych trzech pól tożsamości, aby zbudować klucz idempotentny; nie traktuj identyfikatora zamówienia warunkowego, identyfikatora zamówienia i identyfikatora wypełnienia jako tego samego numeru.

data Zawiera pola, takie jak cena, ilość, status, wydatek, zysk i strata lub zmiana salda według zasobu. Kwota, cena, ilość i identyfikator jednostki są traktowane jako ciągi znaków; czas biznesowy jest podawany w milisekundach. Brakujące pola nie są uzupełniane do wartości 0 i nie są wnioskowane z innych podmiotów.

Kursor to pozycja stronicowania zapytania, a nie niezawodna subskrypcja przyrostowa ani gwarantowana migawka atomowa między stronami. Aktualny kursor obowiązuje przez 24 godziny od pierwszej rundy generowania; kolejne strony zachowują tych samych sprzedawców, zasoby, kolekcje graczy i warunki filtrów. Stałe okno historycznego ściągania jest idempotentne przy wielokrotnym wyciąganiu; status bieżącego zamówienia/pozycji jest odświeżany po ponownym zapytaniu. Gdy potrzebny jest interfejs czasu rzeczywistego, używany jest mechanizm danych frontonu platformy, a interfejsu odpytywania szóstego nie można uważać za interfejs rynkowy o wysokiej częstotliwości.

Błędy i odzyskiwanie

HTTP sukces nie oznacza sukcesu biznesowego, musisz sprawdzić code. Java SDK zgłosi błąd biznesowy jako AgentApiException.

cursor i wszystkie warunki filtra oryginalnej strony, która uległa awarii, zostaną zachowane po ograniczeniu prądu, przekroczeniu limitu czasu lub tymczasowej awarii; za każdym razem, gdy zostanie ponownie wywołane SDK, zostaną wygenerowane nowe timestamp, nonce, sign. Nie możesz przejść bezpośrednio do następnej strony i nie możesz traktować niepowodzeń jako pustych rezultatów. SDK nie jest odpowiedzialny za automatyczne ponawianie transakcji funduszami.

Wspólna odpowiedź i paginacja

Struktura każdego data.items[]:

To samo ledgerId może oddzielić wiele szczegółów, takich jak opłaty manipulacyjne, zyski i straty itp.; naciśnięcie ledgerId w celu usunięcia duplikatów spowoduje utratę danych. Nie można mieszać identyfikatorów z różnych zasobów. Zobacz powiązany przewodnik w Przewodniku dostępu, aby zapoznać się z zasadami stronicowania i zapisywania pól.

Rodzaje, jednostki i pola pomijane

• Kwota, cena, ilość i ciąg znaków identyfikacyjny jednostki; używaj liczb dziesiętnych do przetwarzania kwot i nie możesz używać liczb zmiennoprzecinkowych ani konwertować długich identyfikatorów na liczby JavaScript. Waluta kwoty i jednostka ilości są wyjaśnione zgodnie ze specyfikacjami pary handlowej/kontraktu.
• Czas biznesowy wykorzystuje liczbę całkowitą (int64), obie są milisekundami uniksowymi; sygnatura czasowa żądania uwierzytelnienia i dane uwierzytelniające expireAt używają sekund i nie można ich pomylić.
• Pola biznesowe typu string zwykle nie są wyświetlane, gdy są puste, a niektóre zostaną pominięte, gdy pola numeryczne mają wartość 0. Brakujące pole nie oznacza, że ​​wartość biznesowa wynosi 0.
• reduceOnly, closeOnly, makerOnly w ogólnym modelu rekordu nie pomijają fałszu, więc te trzy fałsze mogą również pojawić się w transakcjach lub pozycjach. Są one wyjaśnione jedynie w zasobach zamówienia; nie można uznać, że transakcja/pozycja wykonała odpowiednie reguły dotyczące zleceń.
• closePosition to opcjonalna wartość logiczna: dostarczana przez zamówienia warunkowe, zwykle pomijana w przypadku innych zasobów. Brak ma inne znaczenie niż fałsz.
• Poniższa tabela „obecnie dostępna” oznacza, że ​​logika odczytu ma źródło pola; pola opcjonalne można w dalszym ciągu pominąć, ponieważ nie mają one żadnej wartości. Nie ma gwarancji, że pola istniejące w modelu zostaną wypełnione w każdym interfejsie.

Różnica między trybem statusu i marginesu

Pisownia CANCELED w przypadku zamówienia zwykłego różni się od pisowni CANCELLED w przypadku zamówienia warunkowego; uruchomienie zlecenia warunkowego nie oznacza, że ​​wygenerowane zlecenie zwykłe zostało zrealizowane. Nie używaj ponownie tego samego zestawu tabel translacji statusów dla wszystkich zasobów.

Kolejność warunkowa marginMode zwraca CROSS / ISOLATED; historyczne zwykłe zlecenia i pozycje obecnie zwracają „1” / „2”, które stanowią odpowiednio depozyt krzyżowy/izolowany. marginMode nie jest obecnie dostępny dla zwykłych zamówień. Sprzedawcy mogą normalizować zasoby we własnej warstwie wyświetlania, a oryginalne wartości nadal muszą zostać zapisane.

Pola zadeklarowane w modelu, ale nie podane w tym zapytaniu

Generic RecordData / Java Model PerpetualData deklaruje również następujące pola, ale bieżąca logika odczytu produkcyjnego sześciu kategorii nie wypełnia ich. **Nie należy podawać jako dostępnych danych biznesowych ani nie należy zastępować rzeczywistych wyników wartościami domyślnymi pól. **

Rzeczywisty zakres zastosowań terenowych podlega powyższym tabelom zasobów; w przypadku aktualizacji pól lub wyliczeń platforma zostanie dostosowana zgodnie z nowym opisem interfejsu i wersją SDK.

Źródło i powiązane przewodniki

• Oficjalne źródło v0.3.0
• Portfel finansowania
• Przewodnik po aktualizacji