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