Tham chiếu API

Tải lên

Tải tệp hoặc các phần qua HTTP, kiểm tra các phần đã nhận, ghép thành tệp hoặc tệp đính kèm và theo dõi hoặc dọn dẹp tác vụ tải lên.

Định nghĩa kiểu

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

Thao tác

http

POST /upload

info là các byte thô của gói yêu cầu đã mã hóa cho POST /upload, không phải văn bản hay Base64, và phải gửi trước file. Khi thành công, HTTP 201 trả về tên tệp đã lưu thực tế dưới dạng văn bản thuần.

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

Gửi các byte mã hóa thô trong info của POST /upload_chunk trước file. Khi thành công, HTTP 201 trả về index:size dưới dạng văn bản thuần. Kiểm tra uploadedChunks, sau đó gọi mergeChunks hoặc mergeAppFileChunks và xem kết quả qua 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

Nhận thông tin hoàn tất hoặc thất bại của ghép khối tải lên bất đồng bộ.

graphql
subscription uploadMergeResult {
  uploadMergeResult { fileId ok value mergedSize error }
}
mutation

deleteChunks

Xóa mọi khối đã lưu của fileId tải lên theo khối. Dùng sau khi hủy hoặc tải thất bại để giải phóng đĩa.

graphql
mutation deleteChunks($fileId: String!) {
  deleteChunks(fileId: $fileId)
}
mutation

mergeChunks

Bắt đầu ghép các khối đã tải lên thành tệp đích; kiểm tra mergeStatus để biết hoàn tất.

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

Đọc tiến độ hoặc lỗi ghép tải lên; trạng thái NONE nghĩa là chưa bắt đầu ghép cho ID tệp này.

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

Liệt kê chỉ số khối đã nhận cho tải lên theo khối có thể tiếp tục. Dùng để tiếp tục tải lên bị gián đoạn.

graphql
query uploadedChunks($fileId: String!) {
  uploadedChunks(fileId: $fileId) { index sizeBytes }
}