Champs de réponse de l'API d'exportation de données

Chaque point de terminaison de l'API d'exportation de données renvoie un tableau JSON d'objets. Utilisez les tables figurant dans cette rubrique pour interpréter les champs de chaque réponse.

Conventions utilisées dans le présent document de référence

  • Toutes les durées sont exprimées en millisecondes.
  • Toutes les valeurs de date et d'heure sont formatées selon le fuseau horaire spécifié par le paramètre de requête timezone, en utilisant le format YYYY-MM-DDTHH:MM:SS.sss.
  • Les champs d'identifiant (printerId, jobId) restent inchangés d'une requête à l'autre et peuvent être mis en cache par les applications qui s'y intègrent. Le printerId ne change jamais ; ses valeurs peuvent donc être enregistrées et réutilisées d'une session à l'autre.

Champs de réponse de la requête GET /printers

Le point de terminaison /printers renvoie un objet par imprimante identifiée dans le compte et suivie par un collecteur de données.

Zone Type Description
printerName chaîne Le nom d'affichage attribué à l'imprimante dans RICOH Predictive Insight.
printerId chaîne (UUID) L'identifiant unique de l'imprimante. Utilisez cette valeur comme paramètre printerId lorsque vous appelez /jobs, /printer-states ou /printer-interventions.
engines entier Le nombre de modules d'impression dans l'imprimante. Les imprimantes à alimentation en continu peuvent comporter un ou plusieurs moteurs ; les imprimantes à feuilles sont généralement équipées d'un seul moteur. Chaque moteur fait l'objet d'une ligne distincte dans les réponses /printer-states et /printer-interventions.
manufacturer chaîne Le fabricant de l'imprimante, par exemple Ricoh ou InfoPrint.
modèles chaîne Le modèle d'imprimante tel qu'il est indiqué par l'appareil, par exemple RICOH Pro VC80000.
printerMode chaîne Si l'imprimante fonctionne en mode simplex ou duplex. Ce champ peut être absent pour les types d'imprimantes auxquels cette valeur ne s'applique pas, comme les imprimantes à feuilles individuelles.
printerType chaîne Si l'imprimante prend en charge le papier continuous_feed ou cut_sheet.
serialNumber chaîne Le numéro de série indiqué par l'imprimante. Pour les imprimantes à plusieurs moteurs, ce champ peut contenir les numéros de série de chaque moteur sous la forme d'une seule chaîne de caractères, par exemple Printer 1: 10-11111 and Printer 2: 10-11112.
connectionStatus chaîne Indique si RICOH Predictive Insight peut actuellement accéder à l'imprimante. Les valeurs possibles sont connected et not_connected.

Champs de la réponse GET /jobs

Le point de terminaison /jobs renvoie un objet par travail traité par les imprimantes demandées au cours de la période indiquée.

Zone Type Description
printerId chaîne (UUID) L'identifiant de l'imprimante qui a traité le travail. Fait correspondre un printerId issu de la réponse /printers.
jobId chaîne L'identifiant unique du travail.
jobName chaîne Le nom du travail tel qu'il a été transmis à l'imprimante, généralement le nom du fichier source.
jobPrintingSide chaîne Le ou les côtés imprimés pour ce travail, par exemple simplex ou duplex.
jobAction chaîne L'état des travaux au moment du traitement de la demande. Valeurs possibles :
  • printing: le travail était en cours d'impression au moment où la demande a été émise.
  • printing : l'impression du travail s'est terminée avec succès.
  • aborted: les travaux s'ont arrêtés avant la fin de l'impression.
  • completed: le travail a atteint son état final. Cette valeur correspond à un ensemble plus large qui inclut à la fois les travaux printed et les travaux aborted. Utilisez cette fonction lorsque vous souhaitez récupérer tous les travaux qui ne sont plus actifs, quel que soit leur résultat.
jobStartTime chaîne (date-heure) La date et l'heure locales auxquelles l'impression du travail a commencé, dans le fuseau horaire indiqué dans la requête.
jobEndTime chaîne (date-heure) La date et l'heure locales auxquelles les travaux s'ont terminés, dans le fuseau horaire indiqué dans la requête.
jobDuration entier Le temps d'impression écoulé pour ce travail, en millisecondes.
printedCopies entier Le nombre d'exemplaires des travaux produits.
printedPages entier Le nombre total de pages logiques imprimées pour ce travail, toutes copies comprises.
printedImpressions entier Le nombre total d'exemplaires imprimés. Un travail correspond à une face d'une feuille ; ainsi, un travail en recto-verso produit deux impressions par feuille.
printedSheets entier Le nombre total de feuilles utilisées pour ces travaux.
printedRollFeet number Pour les imprimantes à alimentation en continu, la longueur du support consommé par le travail, en pieds.
printedRollMeters number Pour les imprimantes à alimentation en continu, la longueur du support consommé par le travail, en mètres.
inkC, inkM, inkY, inkK number La quantité d'encre cyan, magenta, jaune et noire consommée par le travail, indiquée par canal de couleur en centimètres cubes (cc).
flushingC, flushingM, flushingY, flushingK number Quantité d'encre cyan, magenta, jaune et noire consommée lors des opérations de vidage de la tête d'impression liées à ce travail, indiquée par canal de couleur en centimètres cubes (cc). Les valeurs de vidage sont suivies séparément de inkC/M/Y/K, afin de pouvoir distinguer l'utilisation productive de l'encre de celle liée à l'entretien.

Champs de réponse de la requête GET /printer-states

Le point de terminaison /printer-states renvoie un objet par moteur d'imprimante et par intervalle d'état. Les champs disponibles dépendent du mode de requête :

  • Historique agrégé (par défaut) : tous les champs sont renvoyés.
  • État actuel uniquement (currentState=true) : les champs printerStateDuration, historyStartTime et historyEndTime sont omis.
  • Catégorie d'état uniquement (stateCategoryOnly=true) : printerState est omis.
Zone Type Description
printerId chaîne (UUID) L'identifiant de l'imprimante à laquelle se rapporte cette ligne. Fait correspondre un printerId issu de la réponse /printers.
engine chaîne Le moteur de l'imprimante auquel cette ligne fait référence, par exemple engine_1, engine_2 ou engine_3. Une imprimante dotée de plusieurs moteurs renvoie une ligne par moteur pour chaque intervalle d'état.
stateCategory chaîne La catégorie de niveau supérieur à laquelle appartient l'état du moteur. Les valeurs possibles sont up, down, idle et unknown. Utilisez ce champ pour les tableaux de bord et les rapports qui nécessitent des catégories homogènes pour l'ensemble des modèles d'imprimantes.
printerState chaîne L'état brut signalé par le moteur d'impression, tel que Printing, Preparing, Maintenance ou Sleeping. Les valeurs brutes varient selon le modèle d'imprimante. Omise lorsque stateCategoryOnly=true.
Remarque: Consultez États de l'imprimante et catégories d'états pour obtenir la liste complète des états et de leurs correspondances.
printerStateDuration entier La durée pendant laquelle le moteur est resté dans cet état, en millisecondes. Omise lorsque currentState=true.
historyStartTime chaîne (date-heure) La date et l'heure locales auxquelles le moteur est entré dans cet état, dans le fuseau horaire indiqué dans la requête. Omise lorsque currentState=true.
historyEndTime chaîne (date-heure) La date et l'heure locales auxquelles le moteur a quitté cet état, dans le fuseau horaire indiqué dans la requête. Pour l'intervalle le plus récent d'une réponse agrégée, cette valeur peut correspondre à la fin de la plage de temps demandée. Omise lorsque currentState=true.

Champs de réponse de la requête GET /printer-interventions

Le point de terminaison /printer-interventions renvoie un objet par événement d'intervention, pour chaque moteur de chaque imprimante demandée, dans la plage de temps demandée.

Zone Type Description
printerId chaîne (UUID) L'identifiant de l'imprimante à laquelle se rapporte cette ligne. Fait correspondre un printerId issu de la réponse /printers.
interventionStartDate chaîne (date-heure) La date et l'heure locales auxquelles l'événement a commencé, dans le fuseau horaire indiqué dans la requête.
interventionEndDate chaîne (date-heure) La date et l'heure locales auxquelles l'événement a été résolu, dans le fuseau horaire indiqué dans la requête.
durée entier La durée de l'événement, en millisecondes.
description chaîne Une brève description de la condition à l'origine de l'avertissement ou de l'erreur, par exemple Media empty ou Media empty. Ce champ dépend de la langue : il est affiché dans la langue demandée par le paramètre language, ou en anglais si ce paramètre est omis ou si la description n'est pas disponible dans la langue demandée.
engine chaîne Le moteur de l'imprimante auquel cette ligne fait référence, par exemple engine_1, engine_2 ou engine_3. Une imprimante dotée de plusieurs moteurs renvoie une ligne par moteur pour chaque événement.
jobName chaîne Le nom du travail d'impression en cours au moment où l'événement s'est produit. Cette valeur correspond à une chaîne vide lorsqu'aucun travail n'était associé à l'événement.
interventionCode chaîne Un code permettant d'identifier cette condition. Contrairement à description, cette valeur est indépendante de la langue ; utilisez-la donc lorsque vous devez regrouper ou comparer des événements dans différentes langues. Le format du code dépend de l'imprimante : les imprimantes à feuilles individuelles renvoient une chaîne descriptive telle que coverOpen, tandis que les imprimantes à alimentation en continu renvoient une valeur telle que CA00 ou 40000006.

In this section:

  1. États de l'imprimante et catégories d'états
    Le point de terminaison /printer-states fournit à la fois l'état brut de l'imprimante et une catégorie d'état de haut niveau. Utilisez les tables de cette rubrique pour comprendre quels états bruts relèvent de quelles catégories.
  2. Gestion des limites de réponse de l'API d'exportation de données
    L'API d'exportation de données ne paginera pas les réponses. Si une requête devait renvoyer plus de données que ce que l'API autorise dans une seule réponse, la requête échouerait et générerait une erreur, plutôt que de renvoyer un résultat partiel. Planifiez vos intégrations de manière à respecter les limites en réduisant la plage de dates, en diminuant le nombre d'imprimantes par requête, ou les deux.
Rubrique parente : Utilisation de l'API d'exportation de données