Truy vấn & phân trang vĩnh viễn

Hướng dẫn này hướng tới Agent Java SDK v0.3.0, Java 8+ và hợp đồng công khai được gắn thẻ. Các ví dụ chạy trong phần phụ trợ của đối tác sau khi khởi tạo client trong Bắt đầu nhanh.

Điều kiện tiên quyết mẫu

Đoạn mã Java chia sẻ những nội dung nhập này. Khởi tạo client bằng cách sử dụng Bắt đầu nhanh và lấy platformUserId từ liên kết đã lưu. ID người dùng/đơn đặt hàng mẫu phải được thay thế bằng các giá trị cố định của riêng bạn.

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

Truy vấn dữ liệu hợp đồng vĩnh cửu

Sáu loại giao diện và phương thức Java

Tất cả các yêu cầu đều được ký POST với tiền tố chung là /v1/agent/perpetual.

platformUserIds là một chuỗi ID nền tảng công cộng. Khi được chỉ định, cần có 1 đến 100 người chơi duy nhất có quyền truy cập; trên các điểm cuối cho phép bỏ qua, chỉ có phạm vi người chơi trực tiếp mà người bán hiện tại có quyền truy cập mới được truy vấn. Các truy vấn điền vào giao dịch luôn yêu cầu mảng này; truy vấn thứ tự có điều kiện cũng yêu cầu ID người dùng rõ ràng. Thiếu sót không tương đương với [] và mảng trống là bất hợp pháp. Phạm vi được xác định bởi người bán ký tên và các ID người bán khác không thể được chuyển để mở rộng phạm vi.

Các giá trị mảng được tuần tự hóa dưới dạng JSON nhỏ gọn trước khi tham gia tải trọng ký. Ví dụ: platformUserIds ký hiệu là ["1188041528"], cung cấp platformUserIds=["1188041528"] trong tải trọng k=v. Giữ nguyên thứ tự phần tử mảng, dấu ngoặc kép và ID chuỗi; không chèn khoảng trắng định dạng hoặc sử dụng Java List.toString() (chẳng hạn như [1188041528]). SDK tự động xử lý việc tuần tự hóa này.

Truy vấn thứ tự phải vượt qua orderCategory=NORMAL hoặc CONDITIONAL. Sử dụng orderId cho các lệnh thông thường và conditionId cho các lệnh có điều kiện. Chúng không thể được trộn lẫn giữa các danh mục. Lệnh có điều kiện và lệnh thông thường được tạo bằng cách kích hoạt chúng được xử lý riêng biệt dưới dạng thực thể.

Điều kiện lọc

Thời gian của truy vấn lịch sử là Unix mili giây và khoảng thời gian là [startTime, endTime); thời điểm yêu cầu chữ ký là timestamp là Unix giây. Bạn nên sửa cửa sổ thời gian và truy vấn UTC theo từng phân đoạn; sử dụng UTC để đối chiếu hàng ngày. Trạng thái và loại liệt kê hợp đồng nền tảng sử dụng và bản thân chúng không được dịch sang chuỗi tiếng Trung.

limit Mặc định là 500, phạm vi là 1~1000; kích thước trang không đảm bảo rằng cùng một số sẽ được trả về mỗi lần. Sáu giao diện hiện chia sẻ hạn mức truy vấn 2 lần mỗi giây và 4 cụm cho mỗi người bán, đồng thời giới hạn đồng thời tối đa cho mỗi người bán trong phiên bản là 2. Phía người bán sử dụng hàng đợi thống nhất và bạn nên bắt đầu với phân trang tuần tự và cửa sổ lịch sử nhỏ hơn.

Java ví dụ về truy vấn

Truy vấn thứ tự thông thường hiện tại của người chơi:

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

Truy vấn các thay đổi hợp đồng trong giờ qua và xử lý con trỏ. Ví dụ sau không tự động thử lại; khi ứng dụng thực tế gặp phải giới hạn hiện tại hoặc lỗi tạm thời, hãy làm theo hướng dẫn liên quan được liên kết để khôi phục cùng một trang.

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

Cấu trúc trả về và quy tắc lưu

Nhìn thấy Phản hồi và phân trang chung cho các trường được chia sẻ. Các trường tài nguyên được ghi lại trong Đơn đặt hàng, Giao dịch lấp đầy, Vị trí Và Sổ hợp đồng.

Sáu giao diện trả về thống nhất PerpetualResponse:

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

Mỗi items chứa platformUserId, entityType, entityId, data. Các loại thực thể bao gồm ORDER, CONDITION_ORDER, TRADE_FILL, POSITION, ACCOUNT_LEDGER. Sử dụng ba trường nhận dạng này để tạo khóa bình thường; không coi ID đơn hàng có điều kiện, ID đơn hàng và ID điền là cùng một số.

data Cung cấp các trường như giá, số lượng, trạng thái, chi phí, lãi và lỗ hoặc thay đổi số dư theo tài nguyên. Số tiền, giá, số lượng và ID thực thể được xử lý dưới dạng chuỗi; thời gian kinh doanh tính bằng mili giây. Các trường bị thiếu không được điền vào 0 và không được suy ra từ các thực thể khác.

Con trỏ là vị trí phân trang của một truy vấn, không phải là đăng ký gia tăng đáng tin cậy cũng không phải là ảnh chụp nhanh nguyên tử xuyên trang được đảm bảo. Con trỏ hiện tại có hiệu lực trong 24 giờ kể từ vòng tạo đầu tiên; phân trang tiếp theo vẫn giữ nguyên các thương gia, tài nguyên, bộ sưu tập người chơi và điều kiện lọc. Cửa sổ cố định cho lực kéo lịch sử là bình thường khi được kéo liên tục; trạng thái của đơn hàng/vị trí hiện tại được làm mới sau khi truy vấn lại. Khi cần giao diện thời gian thực, cơ chế dữ liệu của giao diện người dùng nền tảng sẽ được sử dụng và giao diện thăm dò sáu không thể được coi là giao diện thị trường tần số cao.

Lỗi và phục hồi

HTTP thành công không có nghĩa là thành công trong kinh doanh, bạn phải đánh dấu vào code. Java SDK sẽ đưa ra lỗi kinh doanh dưới dạng AgentApiException.

cursor và tất cả các điều kiện lọc của trang ban đầu bị lỗi sẽ được giữ lại sau khi giới hạn hiện tại, hết thời gian chờ hoặc lỗi tạm thời; mỗi lần SDK được gọi lại, timestamp, nonce, sign mới sẽ được tạo. Bạn không thể chuyển thẳng sang trang tiếp theo và bạn không thể coi thất bại là kết quả trống rỗng. SDK không chịu trách nhiệm về việc tự động thử lại các giao dịch quỹ.

Phản hồi và phân trang chung

Cấu trúc của mỗi data.items[]:

Cùng một ledgerId có thể phân tách nhiều chi tiết như phí xử lý, lãi lỗ, v.v.; nhấn ledgerId để xóa trùng lặp sẽ gây mất dữ liệu. Không thể trộn lẫn ID từ các nguồn khác nhau. Xem hướng dẫn liên quan được liên kết của Hướng dẫn truy cập để biết các quy tắc phân trang và lưu trường.

Loại, đơn vị và các trường bị bỏ qua

• Chuỗi sử dụng số lượng, giá cả, số lượng và ID thực thể; sử dụng số thập phân để xử lý số tiền và không thể sử dụng số dấu phẩy động hoặc chuyển đổi ID dài thành Số JavaScript. Số lượng tiền tệ và đơn vị số lượng được giải thích theo thông số kỹ thuật của cặp giao dịch/hợp đồng.
• Thời gian kinh doanh sử dụng số nguyên (int64), cả hai đều là mili giây Unix; yêu cầu dấu thời gian xác thực và thông tin đăng nhập expireAt sử dụng giây và không thể nhầm lẫn.
• Các trường kinh doanh chuỗi thường không được xuất ra khi chúng trống và một số trường sẽ bị bỏ qua khi trường số bằng 0. Trường bị thiếu không có nghĩa là giá trị kinh doanh là 0.
• reduceOnly, closeOnly, makerOnly trong mô hình bản ghi chung không bỏ sót sai, vì vậy ba sai này cũng có thể xuất hiện trong các giao dịch hoặc vị thế. Chúng chỉ được giải thích trong tài nguyên đặt hàng; không thể coi giao dịch/vị trí được thực hiện theo các quy tắc lệnh tương ứng.
• closePosition là một boolean tùy chọn: được cung cấp bởi các lệnh có điều kiện, thường bị bỏ qua đối với các tài nguyên khác. Thiếu có một ý nghĩa khác với sai.
• Bảng bên dưới “hiện được cung cấp” có nghĩa là logic đọc có nguồn trường; các trường tùy chọn vẫn có thể bị bỏ qua vì chúng không có giá trị. Các trường tồn tại trong mô hình không được đảm bảo sẽ được điền đầy đủ trong mọi giao diện.

Sự khác biệt giữa trạng thái và chế độ ký quỹ

Cách viết của CANCELED đối với lệnh thông thường khác với CANCELLED đối với lệnh có điều kiện; việc kích hoạt lệnh có điều kiện không có nghĩa là lệnh thông thường được tạo đã được khớp. Không sử dụng lại cùng một bộ bảng dịch trạng thái cho tất cả các tài nguyên.

Lệnh có điều kiện marginMode trả về CROSS / ISOLATED; các lệnh và vị thế thông thường trong lịch sử hiện trả về “1” / “2”, tương ứng là ký quỹ chéo/cô lập. marginMode hiện không áp dụng cho các đơn hàng thông thường. Người bán có thể chuẩn hóa theo tài nguyên trong lớp hiển thị của riêng họ và vẫn cần lưu các giá trị ban đầu.

Các trường được khai báo trong mô hình nhưng không được cung cấp trong truy vấn này

Generic RecordData / Java Mô hình PerpetualData cũng khai báo các trường sau, nhưng logic đọc sản xuất sáu danh mục hiện tại không điền chúng. **Không được liệt kê dưới dạng dữ liệu kinh doanh có sẵn và các giá trị mặc định của trường cũng không được thay thế cho kết quả thực. **

Phạm vi ứng dụng hiện trường thực tế tuân theo các bảng tài nguyên trên; khi nền tảng cập nhật các trường hoặc bảng liệt kê, nó sẽ được điều chỉnh theo mô tả giao diện mới và phiên bản SDK.

Nguồn và hướng dẫn liên quan

• Nguồn v0.3.0 chính thức
• Ví tiền tài trợ
• Hướng dẫn nâng cấp