API 参考
上传
通过 HTTP 上传文件或分片,查询已收到的分片,将其合并为文件或附件,并跟踪或清理上传任务。
类型定义
graphql
type Subscription {
uploadMergeResult: UploadMergeResult!
}
type Mutation {
deleteChunks(fileId: String!): Boolean!
mergeChunks(fileId: String!, totalChunks: Int!, path: String!, replace: Boolean!, totalSize: Long!): MergeTask!
}
type Query {
mergeStatus(fileId: String!): MergeTask!
uploadedChunks(fileId: String!): [UploadedChunk!]!
}
scalar Long
type MergeTask {
status: MergeTaskStatus!
value: String
mergedSize: Long
error: String
}
enum MergeTaskStatus {
NONE
STARTED
MERGING
DONE
FAILED
}
type UploadMergeResult {
fileId: ID!
ok: Boolean!
value: String
mergedSize: Long
error: String
}
type UploadedChunk {
index: Int!
sizeBytes: Long!
}操作
http
POST /upload
info 必须是绑定到 POST /upload 的原始加密请求封装字节,而不是文本或 Base64。info(包含声明的字节数)必须放在 file 前面。HTTP 201 以纯文本返回实际保存的文件名。
bash
curl 'https://<device-host>:<https-port>/upload' \
-H 'c-id: <client-id>' \
-F 'info=<./encrypted-info.bin' -F 'file=@./example.txt'
# Send info before file. Metadata JSON: { dir, replace, isAppFile, size }
# info contains raw encrypted request-envelope bytes for POST /upload.
# A Bearer header alone does not authenticate multipart uploads.http
POST /upload_chunk
将绑定到 POST /upload_chunk 的原始加密请求封装字节作为 info,放在 file 前面。HTTP 201 以纯文本返回 index:size。检查 uploadedChunks,再调用 mergeChunks 或 mergeAppFileChunks,并通过 mergeStatus 查询异步合并结果。
bash
curl 'https://<device-host>:<https-port>/upload_chunk' \
-H 'c-id: <client-id>' \
-F 'info=<./encrypted-info.bin' -F 'file=@./chunk.bin'
# Metadata JSON: { fileId, index, size }; bind encryption to POST /upload_chunk.
# Inspect uploadedChunks; call mergeChunks with totalSize for normal files,
# or mergeAppFileChunks for app attachments. Poll mergeStatus for completion.subscription
uploadMergeResult
接收异步上传分块合并的完成或失败信息。
graphql
subscription uploadMergeResult {
uploadMergeResult { fileId ok value mergedSize error }
}mutation
deleteChunks
删除分块上传 fileId 对应的全部已存储分块;可在上传取消或失败后释放磁盘空间。
graphql
mutation deleteChunks($fileId: String!) {
deleteChunks(fileId: $fileId)
}mutation
mergeChunks
开始将已上传分块合并为目标文件;通过 mergeStatus 检查完成状态。
graphql
# Starts the merge and returns immediately; completion arrives over the
# websocket, and `mergeStatus` is the polling fallback for a lost event.
mutation mergeChunks($fileId: String!, $totalChunks: Int!, $path: String!, $replace: Boolean!, $totalSize: Long!) {
mergeChunks(fileId: $fileId, totalChunks: $totalChunks, path: $path, replace: $replace, totalSize: $totalSize) { status value mergedSize error }
}query
mergeStatus
读取上传分块的合并进度或失败状态;NONE 表示尚未开始合并此文件 ID。
graphql
# `NONE` when no merge was ever started for this id, which is what a
# client sees before it calls `mergeChunks`.
query mergeStatus($fileId: String!) {
mergeStatus(fileId: $fileId) { status value mergedSize error }
}query
uploadedChunks
列出可续传上传中已接收的分块索引,用于恢复中断的上传。
graphql
query uploadedChunks($fileId: String!) {
uploadedChunks(fileId: $fileId) { index sizeBytes }
}