Gestion des limites de réponse de l'API d'exportation de données

Quelles sont les limites ?

Deux types de restrictions s'appliquent aux requêtes comportant une plage de dates :

Plage de dates maximale

Si l'intervalle entre startDateTime et endDateTime dépasse sept jours, l'API renvoie une réponse 400 avec le code d'erreur ERR_DATE_RANGE_EXCEEDED. Réduisez la durée de la plage horaire demandée, puis renvoyez votre demande.

Taille maximale de la réponse

La taille maximale prise en charge pour un fichier de réponse est de 6 Mo, ce qui devrait être suffisant pour contenir les données de près de 10 000 travaux. Si les données appariées à une requête dépassaient la taille maximale de la réponse, l'API renvoie une réponse 413 avec le code d'erreur ERR_RESPONSE_LIMIT_EXCEEDED. Le corps de la réponse comprend une valeur maxJobs qui indique la limite en vigueur. Pour résoudre ce problème, réduisez la plage de dates, demandez un nombre réduit d'imprimantes, ou les deux, puis renvoyez la demande.

Demandes d'aménagement visant à respecter les limites fixées

Pour concevoir une intégration qui respecte de manière fiable les limites de réponse, tenez compte des facteurs suivants :

• Volume de travaux par imprimante. Une imprimante à haut débit et à alimentation en continu peut produire un nombre bien plus élevé de travaux par heure qu'une imprimante à feuilles individuelles à faible volume. Si vous combinez les deux types d'imprimantes au sein de votre parc, ce sont les imprimantes à haut volume qui déterminent la durée minimale de vos créneaux horaires.
• Nombre d'imprimantes par demande. Chaque requête peut comporter plusieurs valeurs printerId. Regrouper plusieurs imprimantes dans une seule requête est pratique, mais chaque imprimante supplémentaire augmente la taille de la réponse et le risque de dépasser la limite.
• Heure de la journée. Si votre entreprise fonctionne par équipes, les travaux et les changements d'état se concentrent sur certaines heures. Une période de 24 heures peut donner lieu à des volumes très différents selon le moment où ces 24 heures commencent et se terminent.
• Nombre maximal de tentatives autorisées. Si une requête échoue avec le code d'erreur ERR_RESPONSE_LIMIT_EXCEEDED, votre intégration doit fractionner la requête et réessayer. Concevoir dès le départ pour des fenêtres de petite taille est généralement moins complexe que de mettre en œuvre un fractionnement dynamique.

Modèles recommandés

Les modèles suivants conviennent bien aux scénarios d'intégration courants :

Relevé nocturne à des fins de reporting

Exécutez un travail planifié une fois par jour afin de récupérer les données des dernières 24 heures, une imprimante à la fois. Ce modèle est simple à mettre en œuvre, permet de réessayer facilement en cas d'échec et garantit que chaque réponse reste concise. Regroupez les réponses par imprimante dans votre processus en aval.

Extrait horaire pour les tableaux de bord en temps quasi réel

Exécutez un travail planifié une fois par heure afin de récupérer, en un seul appel, les données de l'heure précédente pour toutes les imprimantes. Les intervalles horaires permettent de limiter la taille des réponses, même pour les imprimantes à haut débit. Si votre parc est important, commandez les imprimantes par lots plutôt que toutes en même temps.

Rétroactivité des données historiques

Pour alimenter un entrepôt de données avec des données historiques, parcourez la période concernée par tranches de durée fixe (par exemple, six heures par requête) et traitez vos imprimantes par petits groupes. Traitez une fenêtre à la fois et enregistrez les résultats avant de déplacer la fenêtre vers la suivante. Si une fenêtre génère l'erreur ERR_RESPONSE_LIMIT_EXCEEDED, divisez-la en deux et réessayez avec chacune des deux parties.

État actuel de l'imprimante à des fins de suivi

Pour surveiller l'état actuel de chaque imprimante de votre parc sans récupérer l'historique, appelez /printer-states en spécifiant currentState=true. La réponse comprend une ligne par moteur et n'est pas influencée par la plage de dates ; une seule requête peut donc couvrir l'ensemble de la flotte.

Gestion des erreurs liées à la limite de réponse dans votre intégration

Lorsque vous recevez une réponse 413 accompagnée du code ERR_RESPONSE_LIMIT_EXCEEDED, veuillez effectuer une ou plusieurs des actions suivantes avant de réessayer la requête :

• Réduisez la plage horaire. Diviser la fenêtre en deux est une stratégie fiable ; si la requête ainsi divisée échoue toujours, divisez-la à nouveau.
• Réduisez le nombre de valeurs printerId dans la requête. Si une imprimante est utilisée pour la majeure partie du volume d'impression, veuillez en faire la demande séparément.
• Si la requête porte sur un instantané actuel plutôt que sur l'historique, utilisez currentState=true sur /printer-states afin d'éviter totalement le volume lié à la plage de dates.

Ne réessayez pas d'effectuer la même requête sans modifier les paramètres. L'API ne renvoie pas de résultats partiels ; par conséquent, une nouvelle tentative sans modification échouera à nouveau.