Các tuyến HTTP
Các điểm cuối HTTP xử lý yêu cầu GraphQL, truyền tệp và kết nối thiết bị. Xem định dạng yêu cầu và yêu cầu xác thực của từng điểm cuối bên dưới.
Định nghĩa kiểu
# HTTP
https://<device-host>:<https-port>
POST /graphql
POST /guest_graphql
POST /peer_graphql
GET /fs?id=<resource-id>&action=PREVIEW&size=SM
GET /zip/dir?id=<directory-resource-id>
GET /zip/files?id=<selection-archive-id>
POST /upload
POST /upload_chunk
POST /init
GET /health
POST /nearby
ANY /proxy/:peer/*path
# DLNA
GET/HEAD /dlna/description.xml
GET/HEAD /dlna/av-transport/scpd.xml
GET/HEAD /dlna/rendering-control/scpd.xml
POST /dlna/av-transport/control
POST /dlna/rendering-control/control
SUBSCRIBE/UNSUBSCRIBE /dlna/av-transport/event
SUBSCRIBE/UNSUBSCRIBE /dlna/rendering-control/event
GET/HEAD /dlna/media/:id
NOTIFY /dlna/callback
# WebSocket
wss://<device-host>:<https-port>/graphql?cid=<client-id>
wss://<device-host>:<https-port>/auth?cid=<client-id>
wss://<device-host>:<https-port>/screen?cid=<client-id>
wss://<device-host>:<https-port>/status?cid=<client-id>
wss://<device-host>:<https-port>/image_editor?cid=<client-id>Thao tác
POST /graphql
Điểm cuối GraphQL chính. Chế độ API-token dùng tiêu đề c-id và Authorization: Bearer với JSON; chế độ phiên đăng nhập dùng phần thân đã mã hóa.
curl 'https://<device-host>:<https-port>/graphql' \
-H 'c-id: <client-id>' -H ': Bearer <api-token>' \
-H 'Content-Type: application/json' \
--data '{"query":"{ app { deviceName capabilities access } }"}'GET /fs
Đọc ID tài nguyên đã mã hóa: c.CLIENT_ID.PAYLOAD cho phiên hoặc s.SHARE_ID.PAYLOAD cho chia sẻ đang hoạt động. Liên kết phiên dùng app.urlToken của bên gọi, không dùng token xác thực GraphQL. Giữ kín liên kết; thu hồi phiên làm chúng vô hiệu. Hành động: PREVIEW, DOWNLOAD, PROBE hoặc TRANSCODE; kích thước xem trước: SM hoặc LG; phạm vi byte: HTTP Range. DESCRIBE trả về siêu dữ liệu tệp và các mục thư mục được phép truy cập.
curl 'https://<device-host>:<https-port>/fs?id=<resource-id>&action=PREVIEW&size=SM' -o thumbnail
curl 'https://<device-host>:<https-port>/fs?id=<resource-id>&action=DOWNLOAD' -OJ
curl 'https://<device-host>:<https-port>/fs?id=<resource-id>&action=DESCRIBE'
# describe JSON: {"entry":{"url":"/fs?id=<resource-id>&action=DOWNLOAD","name":"example.txt","isDir":false,"sizeBytes":10},"children":[]}
# action: DESCRIBE | PREVIEW | DOWNLOAD | PROBE | TRANSCODE
# size: SM | LG (PREVIEW only); v: optional cache version
# Byte ranges use the HTTP Range header.
# id: c.<client-id>.<payload> or s.<share-id>.<payload>
# Session links use app.urlToken, not the GraphQL authentication token.
# Keep resource URLs private; revoking the owning session invalidates its links.GET /zip/dir
Tải thư mục được phép truy cập dưới dạng ZIP. Dùng ID tài nguyên /fs thông thường của phiên hoặc ID thư mục trong mục đang được chia sẻ. Máy chủ có thể trả về HTTP 429 khi có quá nhiều tác vụ đồng thời.
curl 'https://<device-host>:<https-port>/zip/dir?id=<directory-resource-id>' -o directory.zipGET /zip/files
Tải các tệp đã chọn dưới dạng ZIP bằng ID ZIP_FILES riêng chỉ dùng trong phiên. Không chấp nhận ID /fs thông thường hoặc ID chia sẻ.
curl 'https://<device-host>:<https-port>/zip/files?id=<selection-archive-id>' -o selection.zipGET /health
Kiểm tra khả năng truy cập không cần xác thực. Trả về phần thân văn bản thuần OK.
curl 'https://<device-host>:<https-port>/health'POST /init
Yêu cầu c-id và bật truy cập từ xa. Phần thân rỗng khám phá cấu hình và trả về authenticated=false. Để kiểm tra phiên hiện có, mã hóa phong bì yêu cầu cho POST /init bằng token xác thực của phiên. Phản hồi gồm httpsPort (0 nếu không có trình lắng nghe HTTPS); opaquePublicKey và các trường bằng chứng TLS có điều kiện.
curl 'https://<device-host>:<https-port>/init' -X POST -H 'c-id: <client-id>'
# An empty body discovers configuration; it does not prove session authentication.
# To check a session, send an encrypted request envelope bound to POST /init.POST /guest_graphql
API mã hóa trong phạm vi chia sẻ có hợp đồng khách riêng. c-id xác định chia sẻ hoạt động; API token không cấp quyền cho yêu cầu khách.
# Share-scoped encrypted GraphQL, not an API-token request.
# c-id: <share-id>; request bound to POST /guest_graphql.
# Contract: plain-core/schema/guest-api.graphqls
query { sharedInfo { name readOnly requiresPassword entries { name relativePath isDir size } } }POST /peer_graphql
c-id: ID máy khách gửi. c-cid: ID kênh trò chuyện. Thông điệp kênh chứa c-cid và dùng khóa kênh; yêu cầu ngang hàng trực tiếp bỏ qua nó và dùng khóa ghép đôi.
curl 'https://<device-host>:<https-port>/peer_graphql' \
-H 'c-id: <sender-client-id>' \
-H 'c-cid: <channel-id>' \
-H 'Content-Type: application/octet-stream' \
--data-binary @peer-request.bin \
--output peer-response.bin