Vai al contenuto principale
Attraverso l’endpoint /v1/files di Olostep puoi caricare file JSON che possono essere utilizzati come contesto nelle tue richieste API. Questo ti permette di fornire dati strutturati per migliorare i tuoi scraping, risposte e altre operazioni.
  • Carica file JSON fino a 200MB
  • I file vengono automaticamente validati per il corretto formato JSON
  • Usa i file come contesto in scraping, risposte e altri endpoint
  • I file scadono dopo 30 giorni
  • Processo di caricamento sicuro tramite URL pre-firmato
Per i dettagli sull’API, consulta la Riferimento API dell’Endpoint File.

​
Installazione

# pip install requests

import requests

​
Carica un file

Il processo di caricamento del file consiste in due passaggi:
  1. Crea URL di caricamento: Richiedi un URL pre-firmato per caricare il tuo file
  2. Completa il caricamento: Carica il tuo file all’URL pre-firmato, quindi chiama l’endpoint di completamento per validare e finalizzare

​
Passaggio 1: Crea URL di caricamento

Per prima cosa, crea un URL di caricamento fornendo il nome del file e lo scopo opzionale. Il parametro purpose supporta solo due valori: "context" (predefinito) o "batch". 
import requests
import json

API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"

# Passaggio 1: Crea URL di caricamento
payload = {
    "filename": "my-data.json",
    "purpose": "context"  # Opzionale, predefinito è "context". Valori supportati: "context" o "batch"
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(f"{API_URL}/files", headers=headers, json=payload)
upload_data = response.json()

print(json.dumps(upload_data, indent=2))
# La risposta include: id, upload_url, expires_in
La risposta include un upload_url pre-firmato che scade in 10 minuti: 
{
  "id": "file_abc123xyz789",
  "object": "file.upload",
  "created": 1760329882,
  "upload_url": "https://olostep-files.s3.amazonaws.com/files/...",
  "expires_in": 600
}

​
Passaggio 2: Carica il file e completa

Carica il tuo file JSON all’URL pre-firmato, quindi chiama l’endpoint di completamento per validare e finalizzare il caricamento. 
import requests
import json

API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"

# Dopo aver ottenuto upload_url dal Passaggio 1
file_id = upload_data["id"]
upload_url = upload_data["upload_url"]

# Prepara i tuoi dati JSON
json_data = {
    "users": [
        {"name": "John Doe", "email": "john@example.com"},
        {"name": "Jane Smith", "email": "jane@example.com"}
    ]
}

# Passaggio 2a: Carica il file all'URL pre-firmato
upload_response = requests.put(
    upload_url,
    data=json.dumps(json_data),
    headers={"Content-Type": "application/json"}
)
upload_response.raise_for_status()

# Passaggio 2b: Completa il caricamento
complete_response = requests.post(
    f"{API_URL}/files/{file_id}/complete",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
file_info = complete_response.json()

print(json.dumps(file_info, indent=2))
L’endpoint di completamento valida il file JSON e restituisce i metadati del file: 
{
  "id": "file_abc123xyz789",
  "object": "file",
  "created": 1760329882,
  "filename": "my-data.json",
  "bytes": 1024,
  "purpose": "context",
  "status": "completed"
}

​
Recupera i metadati del file tramite ID

Recupera i metadati di un file tramite il suo ID. 
file_id = "file_abc123xyz789"
response = requests.get(
    f"{API_URL}/files/{file_id}",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
file_info = response.json()
print(json.dumps(file_info, indent=2))

​
Recupera l’oggetto file tramite ID

Ottieni un URL pre-firmato per scaricare il contenuto JSON di un file completato. Specifica facoltativamente il tempo di scadenza per l’URL di download utilizzando il parametro di query expires_in (predefinito a 600 secondi / 10 minuti). 
file_id = "file_abc123xyz789"
# Ottieni URL di download (scadenza predefinita: 600 secondi)
response = requests.get(
    f"{API_URL}/files/{file_id}/content",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
download_info = response.json()
download_url = download_info["download_url"]

# Scarica il contenuto del file utilizzando l'URL pre-firmato
file_response = requests.get(download_url)
file_content = file_response.json()
print(json.dumps(file_content, indent=2))

# Esempio con scadenza personalizzata (3600 secondi = 1 ora)
response = requests.get(
    f"{API_URL}/files/{file_id}/content?expires_in=3600",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
download_info = response.json()
print(f"Download URL scade in: {download_info['expires_in']} secondi")
La risposta include un download_url pre-firmato che scade dopo il tempo specificato: 
{
  "id": "file_abc123xyz789",
  "object": "file",
  "created": 1760329882,
  "filename": "my-data.json",
  "bytes": 1024,
  "download_url": "https://olostep-files.s3.amazonaws.com/files/...",
  "expires_in": 600
}

​
Elenca i file

Elenca tutti i file completati per il tuo team. Filtra facoltativamente per scopo (valori supportati: "context" o "batch"). 
# Elenca tutti i file
response = requests.get(
    f"{API_URL}/files",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
files = response.json()
print(json.dumps(files, indent=2))

# Elenca i file filtrati per scopo
response = requests.get(
    f"{API_URL}/files?purpose=context",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
context_files = response.json()
print(json.dumps(context_files, indent=2))
La risposta include un elenco di file: 
{
  "object": "list",
  "data": [
    {
      "id": "file_abc123xyz789",
      "object": "file",
      "created": 1760329882,
      "filename": "my-data.json",
      "bytes": 1024,
      "purpose": "context",
      "status": "completed"
    }
  ]
}

​
Elimina un file

Elimina un file e i suoi dati associati dallo storage. 
file_id = "file_abc123xyz789"
response = requests.delete(
    f"{API_URL}/files/{file_id}",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
result = response.json()
print(json.dumps(result, indent=2))

​
Esempio di caricamento completo (scopo context)

Ecco un esempio completo che carica un file JSON con purpose="context": 
import requests
import json

API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"

# Passaggio 1: Crea URL di caricamento
create_response = requests.post(
    f"{API_URL}/files",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={"filename": "user-data.json", "purpose": "context"}
)
upload_data = create_response.json()
file_id = upload_data["id"]
upload_url = upload_data["upload_url"]

# Passaggio 2: Prepara e carica i dati JSON
json_data = {
    "users": [
        {"id": 1, "name": "Alice", "role": "admin"},
        {"id": 2, "name": "Bob", "role": "user"}
    ]
}

upload_response = requests.put(
    upload_url,
    data=json.dumps(json_data),
    headers={"Content-Type": "application/json"}
)
upload_response.raise_for_status()

# Passaggio 3: Completa il caricamento
complete_response = requests.post(
    f"{API_URL}/files/{file_id}/complete",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
file_info = complete_response.json()

print(f"File caricato con successo: {file_info['id']}")
print(f"Dimensione file: {file_info['bytes']} bytes")

​
Esempio di caricamento file batch

Ecco un esempio che carica un file JSON con purpose="batch" contenente dati batch validi che possono essere utilizzati con l’endpoint /v1/batches: 
import requests
import json

API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"

# Passaggio 1: Crea URL di caricamento con purpose="batch"
create_response = requests.post(
    f"{API_URL}/files",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={"filename": "batch-items.json", "purpose": "batch"}
)
upload_data = create_response.json()
file_id = upload_data["id"]
upload_url = upload_data["upload_url"]

# Passaggio 2: Prepara i dati JSON batch (formato valido per l'endpoint /v1/batches)
batch_data = {
    "items": [
        {"custom_id": "item-1", "url": "https://www.google.com/search?q=stripe&gl=us&hl=en"},
        {"custom_id": "item-2", "url": "https://www.google.com/search?q=paddle&gl=us&hl=en"},
        {"custom_id": "item-3", "url": "https://www.google.com/search?q=payment+gateway&gl=us&hl=en"}
    ],
    "parser": {"id": "@olostep/google-search"},
    "country": "US"
}

upload_response = requests.put(
    upload_url,
    data=json.dumps(batch_data),
    headers={"Content-Type": "application/json"}
)
upload_response.raise_for_status()

# Passaggio 3: Completa il caricamento
complete_response = requests.post(
    f"{API_URL}/files/{file_id}/complete",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
file_info = complete_response.json()

print(f"File batch caricato con successo: {file_info['id']}")
print(f"Dimensione file: {file_info['bytes']} bytes")
print(f"Scopo: {file_info['purpose']}")
Il file batch caricato contiene una struttura JSON valida che corrisponde al formato dell’endpoint /v1/batches:
  • items: Array di oggetti con campi custom_id e url
  • parser: Configurazione opzionale del parser
  • country: Codice paese opzionale
Questo file può essere utilizzato come input per operazioni di elaborazione batch.

​
Requisiti del file

  • Formato del file: Sono supportati solo file JSON (è richiesta l’estensione .json)
  • Dimensione del file: Massimo 200MB per file
  • Scadenza: I file scadono dopo 30 giorni
  • URL di caricamento: Gli URL pre-firmati scadono dopo 10 minuti
  • Parametro purpose: Supporta solo i valori "context" o "batch" (predefinito a "context")

​
Prezzi

I caricamenti dei file sono gratuiti. I file sono archiviati in modo sicuro e scadono automaticamente dopo 30 giorni.