API Origini dati

Elenca i preset di origine: configurazioni pronte e testate dell’origine dati json (docs/sources.md, Presets). Ognuno indica quali schede alimenta, i campi che una persona compila (con aiuto, un pattern e un esempio), i segreti di cui ha bisogno e come ottenere ciascuno, con quale frequenza si aggiorna e per quanto tempo una scheda conserva gli ultimi dati, e i dati di chi legge e a quali condizioni.

Crea un’origine da uno di essi con POST /api/sources e preset, settings e secrets, e visualizzane l’anteprima con POST /api/sources/test.

Un preset di origine, come lo mostra l’elenco.

Elenca le origini dati del progetto, le più recenti per prime, al massimo 200 per pagina. Un’origine dati mantiene aggiornate le proprietà dinamiche di una scheda da un indirizzo esterno, a intervalli (docs/sources.md). Ogni origine mostra il proprio stato: l’ultimo tentativo, l’ultimo successo, l’ultima modifica scritta, la prossima esecuzione, il conteggio degli errori e l’ultimo errore.

I segreti non vengono mai restituiti; ciascuno appare come impostato con un indizio mascherato. next_cursor si passa come after per la pagina successiva, null quando non ce ne sono altre.

Crea un’origine dati che scrive le proprietà dinamiche di una scheda da un indirizzo esterno. kind sceglie l’adattatore (ics legge un indirizzo iCalendar o webcal://); config contiene le impostazioni del tipo e secrets le sue credenziali, memorizzate cifrate e mostrate solo come indizio mascherato.

Oppure indica un preset (GET /api/source-presets) e fornisci i suoi settings e secrets al posto di kind e config: l’origine è un’origine json la cui configurazione è costruita dal preset, restituita con il suo preset e settings, e l’intervallo di aggiornamento e il periodo di scadenza usano per impostazione predefinita quelli del preset. Un preset alimenta solo le schede che elenca (source_target_unsupported).

L’origine viene eseguita entro pochi secondi e poi ogni refresh_seconds. Un’esecuzione non riuscita non scrive mai: la scheda conserva l’ultimo documento valido e lo stato dell’origine mostra l’errore. Un’origine alimenta una scheda (source_target_taken), la scheda deve essere una che il tipo può alimentare (source_target_unsupported) e un’organizzazione ha al massimo 200 origini (source_limit_reached).

Usa prima POST /api/sources/test per vedere il documento che l’origine scriverebbe. Aggiunge source.created. Un nuovo tentativo identico con la stessa Idempotency-Key restituisce la stessa risposta per ventiquattro ore.

Mostra l’anteprima di un’origine dati senza salvare né scrivere nulla: recupera l’indirizzo, formatta la risposta per la scheda di destinazione e convalida il documento con la scheda; poi restituisce il documento, se la scheda lo accetta (valid, con validation_error che indica il percorso in caso contrario), gli avvisi e i conteggi dell’esecuzione.

Passa source_id per testare un’origine salvata con gli altri membri come sostituzioni (settings sostituiscono quelli di un’origine creata da un preset); altrimenti sono obbligatori target e, o kind e config, oppure preset, settings e secrets. Un segreto che un’origine salvata conserva viene usato così com’è memorizzato, a meno che la sostituzione non cambi dove punta (source_secret_required).

Un errore di recupero o di elaborazione è source_test_failed con il source_error fisso. Al massimo 30 anteprime al minuto per organizzazione.

Un’origine dati con il suo stato. ETag è la revisione, per If-Match alla modifica successiva.

Modifica un’origine dati. config sostituisce l’intera configurazione; secrets viene unito (una stringa imposta o sostituisce un segreto, null lo rimuove).

Un’origine creata da un preset accetta settings al posto di config: ogni impostazione indicata sostituisce il proprio valore, null ne rimuove una facoltativa, le altre mantengono il proprio, e la configurazione viene ricostruita dal preset (config su una tale origine è invalid_request su config, e settings su un’altra è invalid_request su settings). I suoi segreti sono indicati come li indica il preset.

Un segreto non inviato mantiene il valore, a meno che la modifica punti l’origine verso qualcosa che il suo ambito memorizzato non copre (source_secret_required su secrets.<name>: inseriscilo di nuovo).

Una modifica a destinazione, config, segreti, refresh_seconds o enabled azzera il conteggio degli errori ed esegue l’origine entro pochi secondi; una ridenominazione no. enabled false ferma la pianificazione e conserva l’ultimo documento della scheda. If-Match protegge la revisione. Aggiunge source.updated.

Elimina l’origine dati. La scheda conserva l’ultimo documento scritto dall’origine. If-Match protegge la revisione. Aggiunge source.deleted.

La mappatura delle sale di una fonte di dati che legge le sale di un sistema di prenotazione (tipo momentus): quali sale offre che nessuno schermo mostra (summary.unmapped_rooms) e quali schermi leggono un documento di sala o di area senza un valore che ne indichi una (schermi con stato missing o unknown, con un suggerimento quando il valore è una sala scritta in un altro modo).

Le sale sono quelle dell’ultimo aggiornamento riuscito della fonte; non viene recuperato nulla. Un tipo senza sale risponde source_has_no_rooms.

Sincronizza subito l’origine, in linea (fino a 60 secondi), e la restituisce con il nuovo stato. Una sincronizzazione non riuscita risponde 200 con status.state error e l’errore; non scrive mai. Una sincronizzazione manuale riparte da zero: il conteggio degli errori viene azzerato e l’indirizzo viene letto per intero. source_busy (Retry-After) mentre una sincronizzazione pianificata usa l’origine.

Al massimo 6 sincronizzazioni al minuto per origine.