Vai al contenuto principale
Attualmente disponibile per Batch. Il supporto per scrapes, crawls, maps e answers arriverà presto.
I metadati ti permettono di allegare coppie chiave-valore personalizzate alle risorse Olostep. Questo è utile per tracciare, filtrare, organizzare e memorizzare il contesto insieme alle tue richieste API. I metadati seguono l’approccio di Stripe — semplice, flessibile e coerente su tutti gli endpoint.

​
Casi d’Uso

Tracciamento & Organizzazione

Collega le risorse ai sistemi interni con ID ordini, ID clienti o nomi di progetti.

Filtraggio & Ricerca

Tagga le risorse per un facile recupero e filtraggio nella tua applicazione.

Contesto del Flusso di Lavoro

Memorizza la fase della pipeline, il livello di priorità o le istruzioni di elaborazione.

Traccia di Audit

Registra chi ha avviato una richiesta, i timestamp o le informazioni sulla versione.

​
Aggiungere Metadati alla Creazione

Includi il parametro metadata quando crei una risorsa: 
{
  "url": "https://example.com",
  "metadata": {
    "order_id": "12345",
    "customer_name": "John Doe",
    "priority": "high",
    "internal_ref": "proj-2024-001"
  }
}
I metadati vengono restituiti in tutte le risposte GET successive per quella risorsa.

​
Regole di Validazione

VincoloLimiteEsempio di Errore
Massimo chiavi50"I metadati possono avere un massimo di 50 chiavi. Hai fornito 51 chiavi."
Lunghezza chiave40 caratteri"La chiave dei metadati \"my_very_long_key_name...\" supera il limite di 40 caratteri."
Formato chiaveNessuna parentesi quadra"La chiave dei metadati \"items[0]\" non può contenere parentesi quadre ([ o ])."
Lunghezza valore500 caratteri"Il valore dei metadati per la chiave \"description\" supera il limite di 500 caratteri."
Tipo di valoreSolo stringhe"Il valore dei metadati per la chiave \"count\" deve essere una stringa. Ottenuto oggetto."
Coercizione di Tipo: Numeri e booleani vengono automaticamente convertiti in stringhe.
  • 42 → "42"
  • true → "true"
  • 3.14 → "3.14"
Oggetti e array vengono rifiutati.

​
Aggiornamento dei Metadati (PATCH)

Attualmente disponibile per: solo Batch.Crawls, Scrapes, Maps e Answers non supportano ancora l’aggiornamento dei metadati dopo la creazione.
Puoi aggiornare i metadati su batch esistenti utilizzando l’endpoint PATCH. Gli aggiornamenti utilizzano un comportamento di merge.

​
Operazioni di Aggiornamento

Le nuove chiavi vengono aggiunte mantenendo quelle esistenti.
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"new_key": "new_value"}}'
Prima: {"project": "alpha"}
Dopo: {"project": "alpha", "new_key": "new_value"}
Le chiavi esistenti vengono sovrascritte con nuovi valori.
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"project": "beta"}}'
Prima: {"project": "alpha", "priority": "high"}
Dopo: {"project": "beta", "priority": "high"}
Imposta una chiave su null o "" (stringa vuota) per eliminarla.
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"priority": null}}'
Prima: {"project": "alpha", "priority": "high"}
Dopo: {"project": "alpha"}
Imposta l’intero campo dei metadati su null o "" per rimuovere tutte le chiavi.
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": null}'
Prima: {"project": "alpha", "priority": "high"}
Dopo: {}
Aggiungi, aggiorna ed elimina chiavi in una singola richiesta.
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"project": "gamma", "new_field": "value", "old_field": null}}'
Prima: {"project": "alpha", "old_field": "remove_me"}
Dopo: {"project": "gamma", "new_field": "value"}

​
Riepilogo Comportamento PATCH

OperazioneRichiestaRisultato
Aggiungi chiave{"metadata": {"new": "value"}}Chiave aggiunta, altre preservate
Aggiorna chiave{"metadata": {"existing": "new_value"}}Chiave aggiornata, altre preservate
Elimina chiave{"metadata": {"key": null}}Chiave rimossa, altre preservate
Elimina chiave{"metadata": {"key": ""}}Chiave rimossa, altre preservate
Cancella tutto{"metadata": null}Tutte le chiavi rimosse
Cancella tutto{"metadata": ""}Tutte le chiavi rimosse
Nessuna operazione{"metadata": {}}Nessuna modifica