Scaricare i file di input

Una volta che i file di input sono stati caricati e finalizzati, puoi scaricarli di nuovo tramite l’API.

Presuppone che tu abbia un bundle con file di input finalizzati e disponga dello scope read:bundle.

---

Come funziona

L’endpoint di download restituisce URL firmati pronti all’uso. Scarica i byte dei file direttamente da CDN/S3 senza header Authorization sulla GET, lo stesso schema usato per i download dei file di scansione.

sequenceDiagram
  participant Client as RCAPI client
  participant RCAPI as RCAPI
  participant CDN as CDN / S3

  Client->>RCAPI: GET input-files (page, limit)
  RCAPI-->>Client: items with signed urls + total
  loop for each item
    Client->>CDN: GET url
    CDN-->>Client: file bytes
  end

RCAPI firma il prefisso di input del bundle una volta per richiesta. L’url di ogni elemento è quella firma con un carattere jolly sostituito dal percorso di archiviazione del file, quindi ogni URL in una singola risposta condivide la stessa scadenza.

Endpoint

Metodo	Percorso	Scope	Scopo
GET	/v1/bundles/{bundleId}/input-files	read:bundle	Elencare gli URL di download firmati per i file di input finalizzati

Elencare gli URL di download dei file di input

GET {api_url}/v1/bundles/{bundleId}/input-files?page=1&limit=20
Authorization: Bearer {access_token}

Parametri di query

Parametro	Tipo	Descrizione
page	number	Indice di pagina in base 1 (predefinito 1)
limit	number	Dimensione della pagina (predefinito 20, massimo 20)
sessionId	uuid	Opzionale. Limita i risultati ai file di una sola sessione di caricamento

Non è offerto alcun ordinamento. I file vengono restituiti in un ordine di archiviazione stabile.

Risposta

Un elenco paginato ({ items, total }):

{
  "items": [
    {
      "fileName": "scan.las",
      "url": "https://cdn…/bundles/…/scan.las?X-Amz-…",
      "sessionId": "6ebf0fe5-4428-4b26-a7e4-e3274980123b"
    },
    {
      "fileName": "panorama/2024-07-scan-idx40.jpg",
      "url": "https://cdn…/bundles/…/panorama/2024-07-scan-idx40.jpg?X-Amz-…",
      "sessionId": "6ebf0fe5-4428-4b26-a7e4-e3274980123b"
    }
  ],
  "total": 28
}

Campo	Significato
fileName	Il nome del file di input (il percorso sostituito nel prefisso firmato)
url	URL di download firmato, pronto per il GET senza header di autenticazione
sessionId	Sessione di caricamento a cui appartiene il file
total	Totale dei file di input finalizzati su tutte le pagine

Scaricare i byte

Per ogni elemento, esegui il GET dell’url direttamente. Non è richiesto alcun bearer token; la firma è incorporata nella query string.

import requests

response = requests.get(item["url"])
response.raise_for_status()

with open(local_path, "wb") as handle:
    handle.write(response.content)

URL scaduti

Tutti gli URL in una risposta condividono un’unica scadenza della firma (circa 24 ore, coerente con altri link firmati nell’API). Se un download restituisce 403 Forbidden, l’URL è scaduto. Richiedi una nuova pagina all’endpoint di elenco e riprova.

Paginare bundle di grandi dimensioni

Quando total supera limit, sfoglia i risultati:

import requests

API_URL = "https://<your-regional-api-url>"
TOKEN = "<access_token>"
BUNDLE_ID = "<bundleId>"
LIMIT = 20

headers = {"Authorization": f"Bearer {TOKEN}"}
base = f"{API_URL}/v1/bundles/{BUNDLE_ID}/input-files"

page = 1
while True:
    listing = requests.get(
        base, headers=headers, params={"page": page, "limit": LIMIT}
    ).json()

    for item in listing["items"]:
        local_name = item["fileName"].replace("/", "_")
        data = requests.get(item["url"])
        data.raise_for_status()
        with open(local_name, "wb") as handle:
            handle.write(data.content)
        print(f"Downloaded {item['fileName']}")

    if page * LIMIT >= listing["total"]:
        break
    page += 1

Quando usare questo endpoint

Caso d’uso	Note
Archiviazione	Copia le acquisizioni grezze nel tuo storage dopo il caricamento
Rielaborazione	Scarica gli input localmente, quindi caricali in un nuovo bundle
Audit / verifica	Conferma quali file sono arrivati sul bundle prima dell’elaborazione
Test di integrazione	Round-trip di caricamento e download nelle pipeline CI

Questo endpoint restituisce solo i file di input (ciò che hai caricato). Gli output elaborati (HLOD, nuvole di punti standardizzate e così via) sono esposti come link firmati dei componenti del bundle su GET /v1/site/{siteId}/bundles/{bundleId}. Consulta Recupero degli output elaborati.

Casi di errore

Stato	Causa
403 Forbidden	Scope read:bundle mancante o nessun permesso di lettura sul bundle
404 Not Found	bundleId sconosciuto

Un array items vuoto con total: 0 significa che il bundle non ha ancora file di input finalizzati. Completa prima una sessione di caricamento; consulta Caricare dati in un Data Bundle.