Référence de l'API

Téléversements

Téléverser des fichiers ou des fragments par HTTP, vérifier les fragments reçus, les fusionner en fichiers ou pièces jointes et suivre ou nettoyer les tâches.

Définitions de types

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

Opérations

http

POST /upload

info contient les octets bruts de l’enveloppe chiffrée pour POST /upload, et non du texte ni du Base64. Envoyez info avant file. En cas de succès, le corps texte HTTP 201 contient le nom réel du fichier enregistré. Les métadonnées doivent inclure la taille déclarée en octets ; leur réutilisation est refusée.

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

Envoyez, dans info, les octets bruts de l’enveloppe chiffrée pour POST /upload_chunk avant file. HTTP 201 renvoie du texte au format index:size. Consultez uploadedChunks, appelez mergeChunks ou mergeAppFileChunks, puis suivez mergeStatus. La fusion est asynchrone.

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

Recevoir les informations de fin ou d’échec d’une fusion asynchrone de fragments téléversés.

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

deleteChunks

Supprimer tous les fragments stockés pour le fileId d’un téléversement fragmenté. À utiliser après une annulation ou un échec pour libérer de l’espace disque.

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

mergeChunks

Démarrer la fusion des fragments téléversés en un fichier de destination ; consulter mergeStatus pour vérifier la fin.

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

Lire la progression ou l’échec d’une fusion de téléversement ; l’état NONE indique qu’aucune fusion n’a commencé pour cet ID de fichier.

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

Lister les indices des fragments déjà reçus d’un téléversement fragmenté reprenable. Sert à reprendre les téléversements interrompus.

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