GET/v1/uploads/{upload_id}
Ottenere un caricamento
get_upload
Restituisce lo stato del caricamento e le parti ricevute (parts: numero, dimensione, SHA-256 ed ETag di ciascuna), così dopo un’interruzione della connessione il client invia solo le parti mancanti. status: pending attende le parti e complete, processing indica che il file è in fase di assemblaggio e di controllo, ready che può essere usato, rejected che è stato rifiutato (reject_reason), consumed che è già stato usato, ed expired che il suo tempo è scaduto. Il caricamento di un altro chiamante restituisce 404 uploads.not_found. Aggiunto nella 1.62.0.
Autenticazione
Invia una chiave API nell’intestazione Authorization: Authorization: Bearer <chiave>.
Parametri di percorso
upload_idstringobbligatorioID del caricamento (
upl_seguito da 32 caratteri esadecimali).length ≤ 64
Risposte
200Risposta riuscita
Intestazioni della risposta
RateLimit-PolicyLimiti in vigore, nel formato della bozza IETF
draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole"<name>";q=<quota>;w=<window in seconds>.keyè la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione èuser, senza credenzialiip);minute,dayemonthsono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.RateLimitQuanto resta di ciascun limite di
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite della voce più restrittiva di
RateLimit-Policy(quella con meno richieste rimanenti).X-RateLimit-RemainingRichieste rimanenti nel limite più restrittivo.
X-RateLimit-ResetSecondi che mancano all’azzeramento del limite più restrittivo.
application/json
idstringobbligatorioL’ID del caricamento (
upl_seguito da 32 caratteri esadecimali).filenamestringobbligatorioIl nome del file (senza cartelle).
content_typestringobbligatorioIl tipo di contenuto dichiarato; vuoto se non dichiarato.
sizeinteger (int64)obbligatorioLa dimensione del file in byte.
sha256string | nullobbligatorioLo SHA-256 del file, dichiarato alla creazione o al
complete;nullse non è ancora noto.part_sizeinteger (int64)obbligatorioLa dimensione di ogni parte tranne l’ultima (da 5 a 100 MiB).
part_countintegerobbligatorioIl numero di parti.
≥ 1, ≤ 1000
parts_receivedintegerobbligatorioIl numero di parti ricevute.
≥ 0
Le parti ricevute per numero (vuoto nella risposta di
POST /v1/uploads).reject_reasonstring | nullobbligatorioIl motivo del rifiuto (
rejected):checksum_mismatch,type_mismatch,unsupported_format,infected,scan_unavailable,unsafe_content. L’enumerazione può crescere;nullse non rifiutato.reject_detailsobject | nullobbligatorioDettagli del rifiuto (l’estensione, il formato dichiarato e quello rilevato, i checksum);
nullse non rifiutato.created_atstring (date-time)obbligatorioMomento della creazione del caricamento.
expires_atstring (date-time)obbligatorioIl termine per completare il caricamento e, una volta pronto, per usarlo.
completed_atstring (date-time) | nullobbligatorioMomento in cui il controllo è terminato (
readyorejected).consumed_atstring (date-time) | nullobbligatorioMomento in cui il caricamento è stato usato (da una scheda, un archivio o un’importazione).
401Non sono state inviate credenziali (né un cookie di sessione né una chiave API), oppure la chiave non è stata trovata.
Intestazioni della risposta
RateLimit-PolicyLimiti in vigore, nel formato della bozza IETF
draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole"<name>";q=<quota>;w=<window in seconds>.keyè la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione èuser, senza credenzialiip);minute,dayemonthsono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.RateLimitQuanto resta di ciascun limite di
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite della voce più restrittiva di
RateLimit-Policy(quella con meno richieste rimanenti).X-RateLimit-RemainingRichieste rimanenti nel limite più restrittivo.
X-RateLimit-ResetSecondi che mancano all’azzeramento del limite più restrittivo.
application/json
403L’azione non è consentita: il ruolo non è sufficiente, manca l’accesso alla raccolta o alla scheda, la richiesta viene eseguita in modalità “View as”, oppure l’organizzazione è sospesa o eliminata (`detail` è un oggetto con `code: org_suspended | org_deleted`).
Intestazioni della risposta
RateLimit-PolicyLimiti in vigore, nel formato della bozza IETF
draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole"<name>";q=<quota>;w=<window in seconds>.keyè la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione èuser, senza credenzialiip);minute,dayemonthsono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.RateLimitQuanto resta di ciascun limite di
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite della voce più restrittiva di
RateLimit-Policy(quella con meno richieste rimanenti).X-RateLimit-RemainingRichieste rimanenti nel limite più restrittivo.
X-RateLimit-ResetSecondi che mancano all’azzeramento del limite più restrittivo.
application/json
404L’oggetto non esiste o non è disponibile per te. L’API non conferma l’esistenza di un oggetto con accesso limitato.
Intestazioni della risposta
RateLimit-PolicyLimiti in vigore, nel formato della bozza IETF
draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole"<name>";q=<quota>;w=<window in seconds>.keyè la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione èuser, senza credenzialiip);minute,dayemonthsono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.RateLimitQuanto resta di ciascun limite di
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite della voce più restrittiva di
RateLimit-Policy(quella con meno richieste rimanenti).X-RateLimit-RemainingRichieste rimanenti nel limite più restrittivo.
X-RateLimit-ResetSecondi che mancano all’azzeramento del limite più restrittivo.
application/json
429Troppe richieste (`api.rate_limited`), la quota dell’organizzazione per il minuto, il giorno o il mese è esaurita (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` e `reset_at`), è stato raggiunto il limite dell’organizzazione, oppure il servizio delle risposte è occupato (`answers.engine_busy`). Attendi il tempo indicato nell’intestazione `Retry-After`.
Intestazioni della risposta
Retry-AfterNumero di secondi da attendere prima di ripetere la richiesta.
RateLimit-PolicyLimiti in vigore, nel formato della bozza IETF
draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole"<name>";q=<quota>;w=<window in seconds>.keyè la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione èuser, senza credenzialiip);minute,dayemonthsono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.RateLimitQuanto resta di ciascun limite di
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite della voce più restrittiva di
RateLimit-Policy(quella con meno richieste rimanenti).X-RateLimit-RemainingRichieste rimanenti nel limite più restrittivo.
X-RateLimit-ResetSecondi che mancano all’azzeramento del limite più restrittivo.
application/json
Codici di errore
Codici che questo endpoint può restituire in error.code, oltre ai codici generali di ogni richiesta.
Limiti di frequenza
Le risposte contengono le intestazioni RateLimit e RateLimit-Policy e le precedenti X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Una risposta 429 contiene Retry-After in secondi: attendi e riprova.