Interprétation des rapports et extraction de données

1. Page récapitulative

Après avoir enregistré la configuration du flux, une page récapitulative s'ouvre et présente toutes les informations nécessaires à l'extraction de données.

Modifier la configuration

Vous pouvez modifier les informations préalablement renseignées en cliquant sur l'onglet « Éditer la configuration du flux ».

Vous pouvez également accéder à cette page via l'onglet « Configurations de flux » en cliquant sur le symbole de l'œil dans la colonne « Actions » du tableau.

2. Éléments d'extraction

Les conditions d'extraction de la source choisie s'affichent sous la forme de trois éléments obligatoires à combiner :

Méthode

GET : protocole de requête utilisé pour récupérer les données.

Autorisation

Bearer Token : clé de sécurité requise pour accéder au contenu.

URL point final

URL au format JSON ou CSV :

https://gate.teeptrak.net/api/....json
https://gate.teeptrak.net/api/....csv

3. Notes importantes

Pagination et limites de requêtes

Les données sont retournées par blocs pour garantir une performance optimale.

Limites de requêtes

• Maximum : 1 requête toutes les 2 secondes par token

• Quota horaire : 500 requêtes par heure par token

Si cette limite est dépassée, l'API retourne une erreur 429 Too Many Requests.

Recommandation : espacez vos requêtes d'au moins 8 secondes pour rester confortablement dans les deux limites.

Résultats par page

Chaque requête retourne un maximum de 2000 résultats par page (2000 lignes). Pour un export de 5000 résultats, il est nécessaire d'effectuer plusieurs requêtes, les résultats étant répartis en blocs de 2000 lignes.

Exception : Le comptage produit est limité à 1000 résultats par page.

4. Exemple de récupération de données

Via l'utilisation de la méthode GET, l'autorisation Bearer Token et l'URL fournie, vous pouvez exporter vos données au format JSON et/ou CSV.

Procédure avec Postman

1. Insérez les informations de l'API dans les champs correspondants de Postman

2. Les données exportées au format JSON s'affichent dans la section inférieure

   

5. Paramètres optionnels et pagination

Il est possible d'appliquer des filtres sur les exportations pour affiner et optimiser vos besoins d'extraction.

Utilisation dans Postman

1. Cliquez sur « Params »

2. Insérez les clés et valeurs correspondantes

3. Cliquez sur « Send » pour valider le filtre

Liste des paramètres disponibles

6. Données brutes - Alternative V2 avec pagination par curseur

Présentation

Pour l'API données brutes, une alternative optionnelle est disponible : l'API Performance Logs V2. Cette API offre une pagination par curseur plus robuste que la pagination classique par numéro de page, garantissant que chaque enregistrement est retourné exactement une fois, même si les données changent entre vos requêtes.

Endpoints V2 :

GET /api/v1/external/performance_logs.json
GET /api/v1/external/performance_logs.csv
GET /api/v1/external/performance_logs/simplified_losses.json
GET /api/v1/external/performance_logs/simplified_losses.csv

Endpoints V1 classiques (toujours disponibles) :

GET /api/v1/external/raw_data
GET /api/v1/external/simplified_losses

Vous pouvez continuer à utiliser la pagination classique par page ou adopter la pagination par curseur selon vos besoins.

Quand utiliser V2 (curseur) ?

• Vous avez une synchronisation régulière de données (quotidienne, horaire, etc.)

• Vous voulez garantir zéro perte ou duplication de données

• Vous gérez de gros volumes et voulez un export CSV en une seule requête

Quand rester en V1 (page) ?

• Vous faites des exports ponctuels simples

• Vous préférez la pagination classique par numéro de page

• Votre intégration existante fonctionne bien avec V1

Pagination par curseur : mode d'emploi

Paramètres V2 spécifiques

Concept

Le curseur est une clé de pagination qui garantit que chaque enregistrement est retourné exactement une fois, même si les données changent entre vos requêtes. Cela offre une meilleure intégrité des données comparé à la pagination simple par numéro de page.

Première requête (synchronisation initiale)

Lancez votre première requête sans curseur, en utilisant le paramètre since ou sans aucun paramètre :

GET /api/v1/external/performance_logs?since=2025-01-01T00:00:00Z

La réponse JSON comprend un objet meta contenant un next_cursor :

json

{
  "data": [ ... ],
  "meta": {
    "next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0wNi0wMVQxMDoxNTowMC4wMDAwMDBaIiwiaWQiOjJ9"
  },
  "links": {
    "next": "https://gate.teeptrak.net/api/v1/external/performance_logs?cursor=eyJ1cGRhdGVkX2F0Ij..."
  }
}

Requêtes suivantes (synchronisation incrémentale)

Sauvegardez le dernier next_cursor reçu. Pour la prochaine requête, utilisez ce curseur comme paramètre :

GET /api/v1/external/performance_logs?cursor=eyJ1cGRhdGVkX2F0IjoiMjAyNS0wNi0wMVQxMDoxNTowMC4wMDAwMDBaIiwiaWQiOjJ9

La réponse retourne un nouveau next_cursor pour la requête suivante. Répétez ce cycle jusqu'à ce que next_cursor soit null, indiquant que vous avez obtenu toutes les données disponibles.

Fin de la pagination

Quand meta.next_cursor vaut null ou que le nombre de résultats est inférieur à la limite, vous avez récupéré tous les enregistrements disponibles.
Afin de poursuivre la requête plus tard, pour obtenir les nouvelles données, il est recommandé de conserver le dernier curseur non null.

Cas d'erreur : curseur perdu

Si vous perdez votre dernier curseur sauvegardé, relancez une requête avec le paramètre since et une date approximative de votre dernière synchronisation réussie. Vous récupérerez alors les données à partir de cette date.

Exemple complet d'une synchronisation sur trois requêtes

1. Synchronisation initiale

Requête 1 : GET /api/v1/external/performance_logs?since=2025-01-01T00:00:00Z
Réponse : 2000 enregistrements + next_cursor = "cursor_ABC"
Sauvegardez "cursor_ABC"

2. Synchronisation incrémentale

Requête 2 : GET /api/v1/external/performance_logs?cursor=cursor_ABC
Réponse : 2000 enregistrements + next_cursor = "cursor_XYZ"
Sauvegardez "cursor_XYZ"

3. Dernière synchronisation incrémentale

Requête 3 : GET /api/v1/external/performance_logs?cursor=cursor_XYZ
Réponse : 1500 enregistrements + next_cursor = "cursor_qsd"
Sauvegardez "cursor_qsd"
Synchronisation terminée

7. Gestion du curseur avec Postman (Variables d'environnement)

Pour automatiser la gestion du curseur dans Postman, utilisez les variables d'environnement.

Configuration initiale

1. Ouvrez Postman et allez dans « Manage Environments » (icône engrenage)

2. Créez ou modifiez votre environnement Gate

3. Ajoutez deux variables :

   • Clé : cursor | Valeur : (laisser vide)

   • Clé : token | Valeur : votre Bearer Token

Première requête

Dans l'onglet Params, ajoutez :

Dans l'onglet Authorization, sélectionnez Bearer Token et entrez votre token.

Cliquez sur Send.

Mise à jour du curseur après chaque réponse

1. Allez dans l'onglet Tests

2. Ajoutez ce script pour sauvegarder automatiquement le next_cursor :

if (pm.response.code === 200) {
  const responseData = pm.response.json();
  if (responseData.meta && responseData.meta.next_cursor) {
    pm.environment.set("cursor", responseData.meta.next_cursor);
    console.log("Curseur sauvegardé :", responseData.meta.next_cursor);
  } else {
    console.log("Fin de pagination : next_cursor est null");
  }
}

Requêtes suivantes

1. Dans l'onglet Params, supprimez le paramètre since

2. Ajoutez le paramètre cursor avec la valeur {{cursor}}

3. Cliquez sur Send

Postman remplacera automatiquement {{cursor}} par la dernière valeur sauvegardée. Après chaque réponse, le script met à jour la variable avec le nouveau curseur.

Répéter jusqu'à la fin

Continuez à envoyer la requête. Le curseur se met à jour automatiquement après chaque appel. Quand next_cursor est null, la synchronisation est terminée.

8. Structure de la réponse V2

Réponse JSON

{
  "data": [
    {
      "id": 1,
      "duration": 300,
      "machine_id": 10,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T11:00:00Z",
      "custom_fields": {
        "Team": "Morning",
        "Line": "L3"
      }
    }
  ],
  "meta": {
    "next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0wNi0wMVQxMDoxNTowMC4wMDAwMDBaIiwiaWQiOjJ9"
  },
  "links": {
    "next": "https://gate.teeptrak.net/api/v1/external/performance_logs?cursor=eyJ..."
  }
}

Éléments clés

Format des dates

Toutes les dates sont retournées au format ISO 8601 en UTC (ex. 2025-01-15T10:30:00Z).

10. Exemples d'intégrations avec V2

Export CSV complet

Pour exporter toutes les données en CSV d'un coup :

GET /api/v1/external/performance_logs.csv?since=2025-01-01T00:00:00Z

Cette requête unique retourne tous les résultats en un seul fichier CSV, sans pagination nécessaire. Idéal pour les exports ponctuels.

Filtrage sur les machines

Pour extraire les données de machines spécifiques :

GET /api/v1/external/performance_logs?cursor=...&machine_ids=10,20,30

Champs personnalisés

Pour inclure les champs personnalisés dans la réponse :

GET /api/v1/external/performance_logs?cursor=...&with_custom_fields=true

Ils apparaîtront dans l'objet with_custom_fields de chaque enregistrement.