Metadati

Attualmente disponibile per Batches. 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 ordine, ID cliente o nomi di progetto.

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, timestamp o 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"
  }
}

import requests

response = requests.post(
    "https://api.olostep.com/v1/batches",
    headers={"Authorization": "Bearer <your_token>"},
    json={
        "items": [{"custom_id": "1", "url": "https://example.com"}],
        "metadata": {
            "project": "q4-analysis",
            "team": "data-ops",
            "priority": "high"
        }
    }
)

const response = await fetch("https://api.olostep.com/v1/batches", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your_token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    items: [{ custom_id: "1", url: "https://example.com" }],
    metadata: {
      project: "q4-analysis",
      team: "data-ops",
      priority: "high"
    }
  })
});

I metadati vengono restituiti in tutte le risposte GET successive per quella risorsa.

Regole di Validazione

Vincolo	Limite	Esempio di Errore
Chiavi massime	50	`"I metadati possono avere un massimo di 50 chiavi. Hai fornito 51 chiavi."`
Lunghezza chiave	40 caratteri	`"La chiave dei metadati \"my_very_long_key_name...\" supera il limite di 40 caratteri."`
Formato chiave	Nessuna parentesi quadra	`"La chiave dei metadati \"items[0]\" non può contenere parentesi quadre ([ o ])."`
Lunghezza valore	500 caratteri	`"Il valore dei metadati per la chiave \"description\" supera il limite di 500 caratteri."`
Tipo di valore	Solo 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: Batches solo.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

Aggiungi nuove chiavi

Le nuove chiavi vengono aggiunte preservando 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"}

Aggiorna chiavi esistenti

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

Elimina chiavi specifiche

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

Cancella tutti i metadati

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: {}

Operazioni miste

Aggiungi, aggiorna ed elimina chiavi in un’unica 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

Operazione	Richiesta	Risultato
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

Comune

Raschiature

Lotti

Scansioni

Mappe

Risposte

Cerca

Monitor

File

Programmi

Recupera

Saldo e Fatturazione

Casi d’Uso

Tracciamento & Organizzazione

Filtraggio & Ricerca

Contesto del Flusso di Lavoro

Traccia di Audit

Aggiungere Metadati alla Creazione

Regole di Validazione

Aggiornamento dei Metadati (PATCH)

Operazioni di Aggiornamento

Riepilogo Comportamento PATCH

​Casi d’Uso

Tracciamento & Organizzazione

Filtraggio & Ricerca

Contesto del Flusso di Lavoro

Traccia di Audit

​Aggiungere Metadati alla Creazione

​Regole di Validazione

​Aggiornamento dei Metadati (PATCH)

​Operazioni di Aggiornamento

​Riepilogo Comportamento PATCH

Casi d’Uso

Aggiungere Metadati alla Creazione

Regole di Validazione

Aggiornamento dei Metadati (PATCH)

Operazioni di Aggiornamento

Riepilogo Comportamento PATCH