L'applicazione Transkribus comunica con il server tramite un insieme di metodi di servizio RESTful.
Visualizzazione con SWADL
Login
La maggior parte dei metodi richiede che l'utente abbia effettuato l'accesso ai servizi, il che si ottiene inviando le credenziali dell'utente al metodo di login:
https://transkribus.eu/TrpServer/rest/auth/login
Il metodo restituisce un XML con il profilo dell'utente e le collezioni a cui questo utente può accedere.
Le richieste successive al servizio devono quindi includere il Session-ID dall'XML o in:
- L'intestazione HTTP come cookie chiamato "JSESSIONID"
- Il parametro di richiesta "JSESSIONID"
Collections
Una volta che un utente è autenticato, le collezioni, per le quali l'utente ha diritti di accesso, possono essere elencate tramite le seguenti chiamate:
https://transkribus.eu/TrpServer/rest/collections/list
La chiamata restituisce una lista di collezioni, dove ogni oggetto contiene l'ID della collezione, il nome della collezione e il ruolo dell'utente corrente in questa collezione.
I documenti in una collezione possono essere elencati analogamente tramite una richiesta GET:
https://transkribus.eu/TrpServer/rest/collections/{collection-ID}/list
Questa chiamata restituisce una lista di oggetti di metadati del documento.
Per recuperare un documento completo, si deve ottenere quanto segue:
https://transkribus.eu/TrpServer/rest/collections/{collection-ID}/{document-ID}/fulldoc
L'oggetto restituito è composto dai metadati del documento e dall'elenco completo delle pagine, dove ogni pagina contiene tra gli altri attributi:
- Un link all'immagine della pagina
- Una lista di file di trascrizione dove ogni trascrizione contiene:
- Un link al file XML della pagina
- L'ID e il nome dell'utente responsabile
- Un timestamp
- Lo stato di modifica della trascrizione, ad esempio NUOVO, IN_PROGRESSO, FATTO, FINALE
Per il POST di una nuova PAGINA XML per una pagina al fine di aggiornare la trascrizione viene dato il seguente percorso:
https://transkribus.eu/TrpServer/rest/collections/{collection-ID}/{doc-ID}/{pageNr}/text
Il metodo accetta i parametri della query:
status: Lo stato di modifica della nuova trascrizione (vedere sopra per i valori)overwritevero o falso. Indica se la versione recente deve essere sovrascritta o no. La sovrascrittura funziona solo se la versione recente è stata salvata dallo stesso utente e lo stato di modifica non è "NEW".
Jobs
Tutte le attività di elaborazione, come la creazione di documenti, l'analisi del layout, l'elaborazione HTR, l'elaborazione OCR, ecc., sono eseguite come thread (jobs) sul server. Ogni lavoro ha uno stato e può essere monitorato e cancellato. Una lista dei lavori può essere recuperata all'indirizzo:
https://transkribus.eu/TrpServer/rest/jobs/list
Le attività possono essere persistenti, ad esempio creazione di documenti, HTR, ecc., o non persistenti, ad esempio lavori di analisi del layout. I primi sono memorizzati nel database, mentre i secondi sono tenuti solo in memoria e vengono rimossi dalla lista dei lavori dopo 1 ora o se il server viene riavviato.
I dettagli di un lavoro specifico possono essere recuperati su:
https://transkribus.eu/TrpServer/rest/jobs/{job-ID}
Per cancellare un lavoro, una richiesta POST deve essere inviata al seguente percorso:
https://transkribus.eu/TrpServer/rest/jobs/{job-ID}/kill
Se un job comprende l'elaborazione di più pagine, per esempio un'analisi del layout o un processo HTR, e ci sono stati problemi con pagine specifiche, i dettagli possono essere interrogati con richieste GET a:
https://transkribus.eu/TrpServer/rest/jobs/{job-ID}/errors
OCR
https://transkribus.eu/TrpServer/rest/recognition/ocr?collId={collection-ID}&id={doc-ID}&pages={pageNr}
POST a questo percorso avvia un lavoro OCR per una specifica pagina di documento. la risposta contiene il job-ID dell'attività OCR, che può essere usato per interrogare lo stato dell'attività (vedi sezione jobs).
Cerca
Ricerca di un testo riconosciuto usando l'indice SOLR:
GET
https://transkribus.eu/TrpServer/rest/search/fulltext?query=XXX&type=LinesLc&filter=collectionId:1234
Parametri: query="stringa di ricerca" type="dove cercare" ("LinesLc" cerca nel testo riconosciuto, senza tenere conto della capitalizzazione) filter="opzioni di filtro" (come standard tutte le collezioni con accesso dell'utente saranno cercate, "collectionId:XXXX" fornirà solo risultati dalla collezione scelta)
