Campi della risposta dell'API di esportazione dei dati

Ogni endpoint dell'API di esportazione dei dati restituisce un array JSON di oggetti. Utilizzi le tabelle riportate in questa sezione per interpretare i campi presenti in ciascuna risposta.

Convenzioni utilizzate nel presente documento di riferimento

  • Tutte le durate sono espresse in millisecondi.
  • Tutti i valori relativi alla data e all'ora vengono formattati in base al timezone specificato dal parametro di richiesta timezone, utilizzando il formato YYYY-MM-DDTHH:MM:SS.sss.
  • I campi identificativi (printerId, jobId) rimangono invariati tra una richiesta e l’altra e possono essere memorizzati nella cache dalle applicazioni integrate. Il printerId non cambia mai, pertanto i valori possono essere memorizzati e riutilizzati tra una sessione e l’altra.

Campi di risposta dell'operazione GET /printers

L'endpoint /printers restituisce un oggetto per ciascuna stampante identificata nell'account e monitorata dalla raccolta dati.

Campo Tipo Descrizione
printerName stringa Il nome visualizzato assegnato alla stampante in RICOH Predictive Insight.
printerId stringa (UUID) L'identificatore univoco della stampante. Utilizzi questo valore come parametro printerId quando effettua una chiamata alle API /jobs, /printer-states o /printer-interventions.
engines intero Il numero di moduli di stampa presenti nella stampante. Le stampanti a alimentazione continua possono essere dotate di uno o più motori; le stampanti a fogli singoli, invece, dispongono in genere di un unico motore. Ogni motore viene riportato come riga separata nelle risposte dei file /printer-states e /printer-interventions.
manufacturer stringa Il produttore della stampante, ad esempio Ricoh o InfoPrint.
model stringa Il modello della stampante indicato dal dispositivo, ad esempio RICOH Pro VC80000.
printerMode stringa Se la stampante sta funzionando in modalità simplex o duplex. Questo campo può essere assente per i tipi di stampante in cui il valore non è applicabile, come ad esempio i dispositivi a fogli singoli.
printerType stringa Se la stampante supporta la carta a continuous_feed o a cut_sheet.
serialNumber stringa Il numero di serie indicato dalla stampante. Nel caso delle stampanti multimotore, questo campo può contenere i numeri di serie di ciascun motore in un'unica stringa; ad esempio, Stampante 1: 10-11111 e Stampante 2: 10-11112.
connectionStatus stringa Indica se, al momento, RICOH Predictive Insight è in grado di connettersi alla stampante. I valori possibili sono connected e not_connected.

Campi della risposta GET /jobs

L'endpoint /jobs restituisce un oggetto per ogni processo elaborato dalle stampanti specificate nell'intervallo di tempo richiesto.

Campo Tipo Descrizione
printerId stringa (UUID) L'identificativo della stampante che ha elaborato il lavoro. È un valore corrispondente a un printerId presente nella risposta /printers.
jobId stringa L'identificatore univoco del lavoro.
jobName stringa Il nome del lavoro così come è stato inviato alla stampante, solitamente il nome del file di origine.
jobPrintingSide stringa Il lato o i lati su cui viene stampato il presente lavoro, ad esempio in modalità simplex o duplex.
jobAction stringa Lo stato del lavoro al momento dell'elaborazione della richiesta. Valori possibili:
  • printing: al momento dell'invio della richiesta, il lavoro era in fase di stampa.
  • imprinting: il lavoro di stampa si è concluso con esito positivo.
  • aborted: il lavoro si è concluso prima che la stampa fosse completata.
  • completed: il lavoro ha raggiunto lo stato finale. Questo valore costituisce un insieme più ampio che comprende sia i lavori printed sia quelli aborted. Utilizzatelo quando desiderate recuperare tutti i lavori che non sono più attivi, indipendentemente dall'esito.
jobStartTime stringa (data e ora) La data e l'ora locali in cui è iniziata la stampa del lavoro, nel fuso orario specificato nella richiesta.
jobEndTime stringa (data e ora) La data e l'ora locali in cui il lavoro è terminato, nel fuso orario specificato nella richiesta.
jobDuration intero Il tempo di stampa trascorso per il lavoro, espresso in millisecondi.
printedCopies intero Il numero di copie prodotte per il lavoro.
printedPages intero Il numero totale di pagine logiche stampate per il lavoro, comprese tutte le copie.
printedImpressions intero Il numero totale di copie stampate. Un'impressione corrisponde a un lato di un foglio; pertanto, un lavoro fronte-retro produce due impressioni per foglio.
printedSheets intero Il numero totale di fogli cartacei utilizzati per i lavori.
printedRollFeet number Per le stampanti a alimentazione continua, la lunghezza del supporto consumato dal lavoro, espressa in piedi.
printedRollMeters number Per le stampanti a alimentazione continua, la lunghezza del supporto consumato dal lavoro, espressa in metri.
inkC, inkM, inkY, inkK number La quantità di inchiostro ciano, magenta, giallo e nero consumata dal lavoro, indicata per ciascun canale di colore in centimetri cubi (cc).
flushingC, flushingM, flushingY, flushingK number La quantità di inchiostro ciano, magenta, giallo e nero consumata durante le operazioni di scaricamento della testina di stampa associate al lavoro, indicata per ciascun canale di colore in centimetri cubi (cc). I valori relativi allo scaricamento vengono monitorati separatamente da inkC/M/Y/K, in modo da poter distinguere l'utilizzo produttivo dell'inchiostro da quello legato alla manutenzione.

Campi della risposta GET /printer-states

L'endpoint /printer-states restituisce un oggetto per ogni motore della stampante, per ogni intervallo di stato. La presenza dei campi dipende dalla modalità di richiesta:

  • Cronologia aggregata (impostazione predefinita): vengono restituiti tutti i campi.
  • Solo stato attuale (currentState=true): printerStateDuration, historyStartTime e historyEndTime vengono omessi.
  • Solo categoria di stato (stateCategoryOnly=true): printerState viene omesso.
Campo Tipo Descrizione
printerId stringa (UUID) L'identificatore della stampante a cui si riferisce questa riga. È un valore corrispondente a un printerId presente nella risposta /printers.
engine stringa Il motore all’interno della stampante a cui si riferisce questa riga, ad esempio engine_1, engine_2 o engine_3. Una stampante dotata di più motori restituisce una riga per ogni motore per ciascun intervallo di stato.
stateCategory stringa La categoria di livello superiore a cui si ricollega lo stato del motore. I valori possibili sono: up, down, idle e unknown. Utilizzi questo campo per i dashboard e i report che richiedono categorie uniformi per tutti i modelli di stampante.
printerState stringa Lo stato grezzo segnalato dal motore di stampa, ad esempio Stampa, Preparazione, Manutenzione o Sospensione. I valori grezzi variano a seconda del modello di stampante. Viene omesso quando stateCategoryOnly=true.
Nota: Si prega di consultare il sito Stati della stampante e categorie di stato per un elenco completo degli Stati e delle relative corrispondenze.
printerStateDuration intero Il tempo, espresso in millisecondi, durante il quale il motore è rimasto in tale stato. Viene omesso quando currentState=true.
historyStartTime stringa (data e ora) La data e l'ora locali in cui il motore è entrato in questo stato, nel fuso orario specificato nella richiesta. Viene omesso quando currentState=true.
historyEndTime stringa (data e ora) La data e l'ora locali in cui il motore ha lasciato questo stato, nel fuso orario specificato nella richiesta. Per l'intervallo più recente in una risposta aggregata, tale valore può corrispondere alla fine dell'intervallo di tempo richiesto. Viene omesso quando currentState=true.

Campi della risposta GET /printer-interventions

L'endpoint /printer-interventions restituisce un oggetto per ogni evento di intervento, per ciascun motore di ciascuna stampante richiesta, nell'intervallo di tempo specificato.

Campo Tipo Descrizione
printerId stringa (UUID) L'identificatore della stampante a cui si riferisce questa riga. È un valore corrispondente a un printerId presente nella risposta /printers.
interventionStartDate stringa (data e ora) La data e l'ora locali in cui l'evento ha avuto inizio, nel fuso orario specificato nella richiesta.
interventionEndDate stringa (data e ora) La data e l'ora locali in cui l'evento è stato risolto, nel fuso orario specificato nella richiesta.
duration intero La durata dell'evento, espressa in millisecondi.
description stringa Una breve descrizione della condizione che ha causato l'avviso o l'errore, ad esempio Supporti di stampa vuoti o Inceppamento carta. Questo campo dipende dalla lingua: viene restituito nella lingua specificata dal parametro language, oppure in inglese qualora tale parametro venga omesso o la descrizione non sia disponibile nella lingua richiesta.
engine stringa Il motore all’interno della stampante a cui si riferisce questa riga, ad esempio engine_1, engine_2 o engine_3. Una stampante dotata di più motori restituisce una riga per ogni motore per ciascun evento.
jobName stringa Il nome del lavoro di stampa in corso al momento in cui si è verificato l’evento. Il valore è una stringa vuota qualora l'evento non riguardasse alcun lavoro.
interventionCode stringa Un codice che identifica la condizione. A differenza della description, questo valore è indipendente dalla lingua; lo utilizzi quindi quando ha bisogno di raggruppare o confrontare eventi tra lingue diverse. Il formato del codice dipende dalla stampante: le stampanti a fogli singoli riportano una stringa descrittiva, ad esempio coverOpen, mentre le stampanti a modulo continuo riportano un valore, ad esempio CA00 o 40000006.

In this section:

  1. Stati della stampante e categorie di stato
    L'endpoint /printer-states riporta sia lo stato grezzo della stampante sia una categoria di stato di alto livello. Utilizzi le tabelle riportate in questa sezione per comprendere quali stati grezzi rientrino nelle diverse categorie.
  2. Gestione dei limiti delle risposte dell'API di esportazione dei dati
    L'API di esportazione dei dati non utilizza la paginazione per le risposte. Qualora una richiesta dovesse restituire una quantità di dati superiore a quella consentita dall’API in una singola risposta, la richiesta fallirà generando un errore anziché restituire un risultato parziale. Pianifichi le Sue integrazioni in modo da rimanere entro i limiti, restringendo l'intervallo di date, riducendo il numero di stampanti per richiesta o entrambe le cose.
Argomento collegato: Utilizzo dell'API di esportazione dei dati