Interpretarea rapoartelor și extragerea datelor

Actualizat acum 28 zile

1. Pagina recapitulativă

După salvarea configurației fluxului, se deschide o pagină recapitulativă care prezintă toate informațiile necesare pentru extragerea datelor.

Modificarea configurației

Puteți modifica informațiile introduse anterior făcând clic pe fila „Editați configurația fluxului”.

De asemenea, puteți accesa această pagină prin fila „Configurații de flux”, făcând clic pe simbolul ochiului din coloana „Acțiuni” a tabelului.

2. Elemente de extragere

Condițiile de extragere ale sursei alese sunt afișate sub forma a trei elemente obligatorii care trebuie combinate:

Metodă

GET: protocolul de cerere utilizat pentru a prelua datele.

Autorizare

Bearer Token: cheie de securitate necesară pentru a accesa conținutul.

URL punct final

URL în format JSON sau CSV:

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

3. Note importante

Paginare și limite de cereri

Datele sunt returnate pe blocuri pentru a garanta o performanță optimă.

Limite de cereri

  • Maximum: 1 cerere la fiecare 2 secunde per token
  • Cotă orară: 500 de cereri pe oră per token

Dacă această limită este depășită, API-ul returnează o eroare 429 Too Many Requests.

Recomandare: distanțați cererile cu cel puțin 8 secunde pentru a rămâne confortabil în ambele limite.

Rezultate pe pagină

Fiecare cerere returnează maximum 2000 de rezultate pe pagină (2000 de rânduri). Pentru un export de 5000 de rezultate, este necesar să efectuați mai multe cereri, rezultatele fiind repartizate în blocuri de 2000 de rânduri.

Excepție: Contorizarea produselor este limitată la 1000 de rezultate pe pagină.

4. Exemplu de preluare a datelor

Prin utilizarea metodei GET, a autorizării Bearer Token și a URL-ului furnizat, puteți exporta datele în format JSON și/sau CSV.

Procedura cu Postman

  1. Introduceți informațiile API-ului în câmpurile corespunzătoare din Postman
  2. Datele exportate în format JSON sunt afișate în secțiunea inferioară

5. Parametri opționali și paginare

Este posibil să aplicați filtre asupra exporturilor pentru a rafina și optimiza nevoile dumneavoastră de extragere.

Utilizare în Postman

  1. Faceți clic pe „Params”
  2. Introduceți cheile și valorile corespunzătoare
  3. Faceți clic pe „Send” pentru a valida filtrul

Lista parametrilor disponibili

Nr. Parametru Descriere
1 page Definește numărul paginii returnate de API
2 created_at_gte Definește pragul „mai mare sau egal cu” (creat la…)
3 created_at_lte Definește pragul „mai mic sau egal cu” (creat la…)
4 updated_at_lte Definește pragul „mai mic sau egal cu” (actualizat la…)
5 with_custom_fields Autorizează afișarea câmpurilor personalizate
6 machine_ids Filtrează cererea pe una sau mai multe mașini

6. Date brute - Alternativa V2 cu paginare prin cursor

Prezentare

Pentru API-ul de date brute, este disponibilă o alternativă opțională: API Performance Logs V2. Acest API oferă o paginare prin cursor mai robustă decât paginarea clasică prin număr de pagină, garantând că fiecare înregistrare este returnată exact o dată, chiar dacă datele se modifică între cererile dumneavoastră.

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 clasice (în continuare disponibile):

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

Puteți continua să utilizați paginarea clasică prin page sau să adoptați paginarea prin cursor, în funcție de nevoile dumneavoastră.

Când să utilizați V2 (cursor)?

  • Aveți o sincronizare regulată a datelor (zilnică, orară etc.)
  • Doriți să garantați zero pierderi sau duplicări de date
  • Gestionați volume mari și doriți un export CSV într-o singură cerere

Când să rămâneți la V1 (pagină)?

  • Efectuați exporturi punctuale simple
  • Preferați paginarea clasică prin număr de pagină
  • Integrarea dumneavoastră existentă funcționează bine cu V1

Paginare prin cursor: mod de utilizare

Parametri specifici V2

Parametru Descriere
since Dată ISO 8601 pentru prima cerere (ex. 2025-01-01T00:00:00Z).
cursor Cheie de paginare pentru cererile următoare. Vedeți mai jos.
limit Numărul de rezultate pe pagină (implicit: 2000, max: 2000)

Concept

Cursorul este o cheie de paginare care garantează că fiecare înregistrare este returnată exact o dată, chiar dacă datele se modifică între cererile dumneavoastră. Aceasta oferă o integritate mai bună a datelor în comparație cu paginarea simplă prin număr de pagină.

Prima cerere (sincronizare inițială)

Lansați prima cerere fără cursor, utilizând parametrul since sau fără niciun parametru:

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

Răspunsul JSON cuprinde un obiect meta care conține un next_cursor:

json

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

Cererile următoare (sincronizare incrementală)

Salvați ultimul next_cursor primit. Pentru următoarea cerere, utilizați acest cursor ca parametru:

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

Răspunsul returnează un nou next_cursor pentru cererea următoare. Repetați acest ciclu până când next_cursor este null, ceea ce indică faptul că ați obținut toate datele disponibile.

Sfârșitul paginării

Când meta.next_cursor are valoarea null sau când numărul de rezultate este mai mic decât limita, ați preluat toate înregistrările disponibile.
Pentru a continua cererea mai târziu, în vederea obținerii datelor noi, se recomandă să păstrați ultimul cursor diferit de null.

Caz de eroare: cursor pierdut

Dacă pierdeți ultimul cursor salvat, relansați o cerere cu parametrul since și o dată aproximativă a ultimei sincronizări reușite. Veți prelua atunci datele începând cu această dată.

Exemplu complet al unei sincronizări în trei cereri

  1. Sincronizare inițială
Cererea 1: GET /api/v1/external/performance_logs?since=2025-01-01T00:00:00Z
Răspuns: 2000 de înregistrări + next_cursor = "cursor_ABC"
Salvați "cursor_ABC"
  1. Sincronizare incrementală
Cererea 2: GET /api/v1/external/performance_logs?cursor=cursor_ABC
Răspuns: 2000 de înregistrări + next_cursor = "cursor_XYZ"
Salvați "cursor_XYZ"
  1. Ultima sincronizare incrementală
Cererea 3: GET /api/v1/external/performance_logs?cursor=cursor_XYZ
Răspuns: 1500 de înregistrări + next_cursor = "cursor_qsd"
Salvați "cursor_qsd"
Sincronizare încheiată

7. Gestionarea cursorului cu Postman (variabile de mediu)

Pentru a automatiza gestionarea cursorului în Postman, utilizați variabilele de mediu.

Configurare inițială

  1. Deschideți Postman și accesați „Manage Environments” (pictograma roată dințată)
  2. Creați sau modificați mediul dumneavoastră Gate
  3. Adăugați două variabile:
    • Cheie: cursor | Valoare: (lăsați gol)
    • Cheie: token | Valoare: Bearer Token-ul dumneavoastră

Prima cerere

În fila Params, adăugați:

Cheie Valoare
since 2025-01-01T00:00:00Z

În fila Authorization, selectați Bearer Token și introduceți token-ul dumneavoastră.

Faceți clic pe Send.

Actualizarea cursorului după fiecare răspuns

  1. Accesați fila Tests
  2. Adăugați acest script pentru a salva automat 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");
  }
}

Cererile următoare

  1. În fila Params, ștergeți parametrul since
  2. Adăugați parametrul cursor cu valoarea {{cursor}}
  3. Faceți clic pe Send

Postman va înlocui automat {{cursor}} cu ultima valoare salvată. După fiecare răspuns, scriptul actualizează variabila cu noul cursor.

Repetați până la sfârșit

Continuați să trimiteți cererea. Cursorul se actualizează automat după fiecare apel. Când next_cursor este null, sincronizarea este încheiată.

8. Structura răspunsului V2

Răspuns 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..."
  }
}

Elemente cheie

Element Descriere
data Tablou care conține înregistrările de performanță
meta.next_cursor Cursor pentru cererea următoare. null dacă paginarea s-a încheiat
links.next URL preconstruit pentru cererea următoare (opțional)
data.custom_fields Obiect care conține câmpurile personalizate (dacă sunt activate)

Formatul datelor calendaristice

Toate datele calendaristice sunt returnate în format ISO 8601, în UTC (ex. 2025-01-15T10:30:00Z).

10. Exemple de integrări cu V2

Export CSV complet

Pentru a exporta toate datele în CSV dintr-o singură dată:

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

Această cerere unică returnează toate rezultatele într-un singur fișier CSV, fără a fi necesară paginarea. Ideal pentru exporturile punctuale.

Filtrare pe mașini

Pentru a extrage datele unor mașini specifice:

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

Câmpuri personalizate

Pentru a include câmpurile personalizate în răspuns:

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

Acestea vor apărea în obiectul with_custom_fields al fiecărei înregistrări.