Interrogazione avanzata — filtrare, proiettare e paginare l'API

Le tre superfici in un colpo d'occhio

Tutte e tre figurano nel riferimento API interattivo (la pagina /developers), sotto la sezione Search, ed esigono un'autenticazione — vedi API Omniscol.

Il filtro where (in stile Mango / MongoDB)

/api/search/entity e /api/search/query accettano entrambi una clausola where: un filtro strutturato a operatori in stile MongoDB. Un campo corrisponde o a un valore diretto (uguaglianza implicita), o a un oggetto di operatori; più operatori sullo stesso campo si combinano con un AND implicito. I nomi dei campi accettano la notazione puntata per raggiungere un contesto padre (ad esempio sites.name).

Qualche esempio:

{ "capacity": { "$gte": 20, "$lte": 50 } }
{ "level": { "$in": ["L1", "L2", "L3"] } }
{ "name": { "$regex": "^lab" } }
{ "city": { "$like": "ivry sur seine" } }
{ "$or": [ { "capacity": { "$gte": 50 } }, { "specialisation": "chemistry" } ] }

Proiezione, ordinamento e paginazione

Su /api/search/query, quattro leve in più mantengono la risposta compatta e ordinata — ciò che conta per una dashboard, e ancor più per un agente IA fatturato a token:

• project — la lista dei campi da conservare (notazione puntata ammessa). Tutto il resto viene scartato.
• sort — un campo, asc o desc. Lo pseudo-campo _count.<campo> ordina secondo la lunghezza di un campo array.
• limit e offset — paginano i risultati.

La risposta restituisce anche un blocco meta: quanti elementi esistevano prima del filtraggio, quanti hanno superato il filtro, e quanti sono stati restituiti.

Un esempio completo

Trovare le aule di almeno 30 posti, conservare solo il loro nome e la loro capacità, dalla più grande alla più piccola, e prendere le prime 20:

curl -X POST "https://vostra-scuola.omniscol.com/api/search/query" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "call": "os_dashboard_classrooms_get",
        "where": { "capacity": { "$gte": 30 } },
        "project": ["name", "capacity"],
        "sort": { "capacity": "desc" },
        "limit": 20
      }'

call è il nome interno dell'endpoint in lettura da eseguire (così come mostrato sulla pagina /developers), params porta i parametri propri di quell'endpoint, e extract_path designa all'occorrenza il array da filtrare all'interno del risultato — omesso qui, viene rilevato automaticamente.

Trovare un'aula o un professore disponibile

L'integrazione più comune — alimentare un intranet, uno strumento di prenotazione o un ETL — è «chi o cosa è libero in tale momento?». Gli endpoint availability vi rispondono direttamente: restituiscono, per entità, solo gli slot liberi sulle date richieste, tenendo già conto delle lezioni, delle assenze e delle disponibilità obbligatorie.

La disponibilità si chiede in due modi:

• Scopata — GET /api/schedules/availability/{datesrange}/{entity} (all'occorrenza /{entityId}) per un tipo di entità — teachers, classrooms, groups, resources…
• Filtro esplicito — GET /api/schedules/availability/{datesrange} con un filter, dove si restringe l'insieme con lo stesso $where visto sopra.

{datesrange} si scrive in YYYYMMDD, e segmenti separati da virgole chiedono date sparse — perfetto per «due lunedì precisi»: 20261005,20261012. Ogni slot restituito porta day, start, end e time (in minuti): «almeno 3 ore» diventa quindi un test time >= 180 dal Suo lato.

Un professore libero su uno slot preciso

«Quali professori sono liberi lunedì 5 ottobre?» — una sola chiamata scopata:

curl -G "https://vostra-scuola.omniscol.com/api/schedules/availability/20261005/teachers" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  --data-urlencode "with_entities=true"

Gli slot liberi tornano raggruppati per natura, poi per professore — ad esempio { "availability": { "teachers": { "t.dupont": [ { "day": "2026-10-05", "start": "14:00", "end": "17:00", "time": 180 } ] } } } — e il Suo strumento trattiene quello che copre lo slot voluto.

Aule di una certa dimensione, libere su due lunedì

Combini un filtro di entità e la disponibilità in una sola chiamata, con un sottoinsieme utile della sintassi — solo $where sulla capacità:

curl -G "https://vostra-scuola.omniscol.com/api/schedules/availability/20261005,20261012" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  --data-urlencode 'filter={"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}' \
  --data-urlencode "with_entities=true"

Omniscol restituisce gli slot liberi, su entrambi i lunedì, di ogni aula di almeno 30 posti. Il Suo ETL trattiene poi le aule che hanno una finestra di 3 ore (time >= 180) su ciascuna delle date — la composizione su più giorni resta dal Suo lato, il che mantiene la regola esplicita e verificabile.

Il filter accetta, per tipo di entità, una semplice lista di identificativi ({"classrooms":["A101","B204"]}), un jolly ({"teachers":"*"}), una corrispondenza di campo semplice ({"teachers":[{"email":"…"}]}) o il $where strutturato mostrato qui.

Scegliere la superficie giusta

• «Dove compare questa parola?» → POST /api/search.
• «A quale entità corrisponde questo nome?» → POST /api/search/entity.
• «Dammi le aule di più di 30 posti, ordinate, prima pagina» → POST /api/search/query.
• «Chi o cosa è libero su questo slot?» → GET /api/schedules/availability/….

Per un agente IA

Queste superfici esistono in gran parte per gli agenti IA. La ricerca full-text e la risoluzione di entità trasformano la formulazione di un utente (« professore Jean Dupont », « classe 6A ») in identificativi precisi; l'orchestratore di query risponde poi a una domanda filtrata in una sola chiamata e restituisce solo i campi richiesti — invece di più chiamate e di una risposta sovradimensionata. Quando collega un agente tramite MCP — collegare un agente IA esterno, questi strumenti fanno parte di ciò che può utilizzare.

Collegarlo a un intranet, un ETL o uno strumento partner

Queste stesse superfici in lettura sono ciò che uno strumento terzo consuma quotidianamente. Forme comuni:

• Un tiraggio verso un intranet o una dashboard — la Sua pagina chiama gli endpoint in lettura (disponibilità, l' endpoint delle lezioni, le dashboard) con un token API ristretto, e mostra il risultato. Nulla da installare lato Omniscol.
• Un ETL notturno — un'attività pianificata recupera ciò di cui ha bisogno (le lezioni su una finestra di date, le ore di un professore, l'occupazione delle aule) e le carica nel Suo sistema informativo. search/query mantiene ogni tiraggio filtrato, proiettato e paginato, per una risposta compatta.
• Una spinta dal Suo sistema — il senso inverso, per mantenere Omniscol allineato alla Sua fonte di verità: un'attività notturna può aggiornare classi e professori (POST /api/external/classes, POST /api/external/teachers) o caricare un catalogo di materie personalizzate (POST /api/admin/subjects/custom) dalla Sua base.
• Un software gestionale SIS / ERP — per Aurion, Auriga e simili, il connettore dedicato è lo strumento adatto — vedi Sincronizzazione con sistemi esterni.
• Guidato dagli eventi — per essere notificato di un cambiamento invece che interrogare in continuazione, registri un hook — vedi Personalizzazione dell'API.

Mantenga ogni integrazione ristretta: un token limitato agli endpoint realmente utili, rinnovato regolarmente, e in sola lettura ovunque non faccia che leggere. Vedi API Omniscol.