Import de données

L'import de données se fait en 2 étapes :

  • Création de la source avec ses données de référence
  • Import des données récentes

Les 2 formats sont similaires pour simplifier l'intégration mais ont un but distinct. Les données de références seront les seules données utilisées lors de l'analyse des profils types et la proposition de planification automatique, alors que les données récentes seront confrontées à la planification pour détecter des éventuelles alertes.

Les données de référence sont utilisées par Timelight pour comprendre la source alors que les données récentes sont vérifiées par Timelight pour alerter en cas d'anomalie.

Notez que le système d'import supporte 2 formats : CSV et JSON.

Import au format CSV

L'import au format CSV permet de créer une source ou d'ajouter des données récentes dans un format fluide pour un système de flux de données.

Format du fichier CSV

Le fichier CSV attendu doit contenir 2 colonnes : la date et la valeur. Il doit être séparé par des point-virgules et échappé par des guillemets. La date doit être au format ISO8601 dans la zone UTC. La valeur doit être au format français.

Notez que nous ne supportons pour le moment que les fichiers CSV triés dans l'ordre chronologique croissant.

Exemple de format CSV accepté :

"Date";"Activité"
"2014-01-01T00:10:00";"64,0"
"2014-01-01T00:20:00";"64,0006"
"2014-01-01T00:30:00";"62,0011"
"2014-01-01T00:40:00";"64,0017"
"2014-01-01T00:50:00";"65,0022"
"2014-01-01T01:00:00";"68,0028"

Interpolation, données manquantes et période d'analyse

Le moteur d'import Timelight permet de configurer une méthode d'interpolation des données manquantes et une période d'analyse.

La période d'analyse détermine l'échantillonnage cible à utiliser lors du moteur. Elle est configurable via le paramètre activitySize à la création de la source. Ce paramètre représente le nombre de points de données maximum par jour pour la source en question.

Par exemple:

  • Fournissez activitySize=144 pour une analyse avec des points de données toutes les 10 minutes
  • Fournissez activitySize=48 pour une analyse avec des points de données toutes les 30 minutes
  • Fournissez activitySize=24 pour une analyse avec des points de données toutes les 1 heure

Si aucun point de donnée n'a été fournis pour un des échantillons, alors le moteur interpolera la donnée selon un algorithme configurable:

  • Fournissez interpolationMethod=zero pour considérer les données manquantes comme un trou de données
  • Fournissez interpolationMethod=linear pour demander au moteur de compléter les données manquantes en utilisant une interpolation linéaire

Création de source

Pour créer une source, vous devez fournir les données de référence associées : une fois ce fichier constitué, vous pourrez utiliser le point d'entrée consacré à la création de source. Nous utilisons la première ligne du fichier de création pour déterminer l'année de référence de la source.

# notez l'utilisation de l'option "-T" et du header "Content-Type: text/csv"
curl -X POST -H "Content-Type: text/csv" \
     -H "Authorization: Bearer ${JWT}" \
     -T ./ma-source.reference.csv \
    "${API_URL}/v1/import-csv/create-source?name=MySource"

Ce premier import de données déclenche une analyse des profils types par notre moteur IA.

Import de données récentes

Les données récentes peuvent être ajoutées à tout moment et à plusieurs reprises à une source. Chaque journée fournie écrase les précédentes données en base pour cette même journée : il est donc impératif de fournir l'intégralité des données disponibles pour chaque journée en cas d'imports quotidiens successifs.

Si des données sont déjà présentes en base pour une date fournie, c'est la nouvelle donnée qui est utilisée. Dans la même logique, toute donnée récente ajoutée invalide les alertes non traitées de cette journée.

Chaque import de données récentes déclenche la vérification de la planification et peut donc déclencher des alertes.

Vous pouvez utiliser le point d'entrée consacré d'import de données récentes en constituant un fichier prenant en compte les points précédents.

# notez l'utilisation de l'option "-T" et du header "Content-Type: text/csv"
curl -X POST -H "Content-Type: text/csv" \
     -H "Authorization: Bearer ${JWT}" \
     -T ./ma-source.days.csv \
    "${API_URL}/v1/import-csv/${SOURCE_ID}/days"

# pour trouver l'ID de la source, utilisez par exemple la méthode "${API_URL}/v1/source/list"

Cet import de données récentes déclenche la vérification des alertes par rapport à la planification.

Import au format JSON

L'import au format JSON est assez restrictif dans son format mais permet une meilleure interopérabilité entre les différents systèmes supportant les appels REST.

Import volumineux de données

L'import au format JSON n'est supporté que pour les fichiers dont la taille ne dépasse pas 200Mb. Pour les imports à la seconde et les imports massifs, veuillez utilisez le format CSV.

Données manquantes

Si vos données contiennent des données manquantes, privéligiez l'import CSV qui propose des options d'interpolation des échantillons manquants

Format des données d'activité

Afin de réduire la taille des JSON échangés entre nos systèmes, nous avons opté pour une forme compacte de représentation de l'activité. Les données sont représentées sous forme d'un tableau de points de données:

  • 4 éléments, représentant chacun une tranche de 6 heures (4 * 6h = 24h)
  • 8 éléments, représentant chacun une tranche de 3 heures (8 * 3h = 24h)
  • 12 éléments, représentant chacun une tranche de 2 heures (12 * 2h = 24h)
  • 24 éléments, représentant chacun une tranche de 1 heure (24 * 3h = 24h)
  • 48 éléments, représentant chacun une tranche de 30 minutes (48 * 30 min = 24h)
  • 72 éléments, représentant chacun une tranche de 20 minutes (72 * 20 min = 24h)
  • 144 éléments, représentant chacun une tranche de 10 minutes (144 * 10 min = 24h)
  • 1440 éléments, représentant chacun une tranche de 1 minute (1440 * 1 min = 24h)
Import échantillonné à la seconde

Si vous souhaitez fournir des données à la seconde, veuillez utiliser les points d'entrées CSV.

Exemple de tableau d'activité pour une journée :

{
    "activity": [
        64.145,
        64.0146,
        65.2,
        65.0,
        // ... 140 more entries
    ],
    "date": "2019-01-01"
}

Pour compatibilité avec d'autres systèmes, nous acceptons également les tableaux d'activité de 1440 éléments (tranches de 1 minute). Notez cependant que notre système d'import fera en sorte de garder les valeurs par tranche de 10 minutes.

Création de source

Pour créer une source, vous devez fournir les données de référence associées au format suivant :

{
  "name": "Ma source",
  "referenceYear": 2014,
  "days": [
    {
      "date": "2014-01-01",
      "activity": [...]
    },
    {
      "date": "2014-01-02",
      "activity": [...]
    },
    // liste des journées de l'année de référence
  ]
}

Une fois ce fichier constitué, vous pourrez utiliser le point d'entrée consacré à la création de source :

curl -X POST -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${JWT}" \
     -d @ma-source.reference.json \
    "${API_URL}/v1/import/create-source"
import timelight_ai_python_api_client as tlc

conf = tlc.Configuration()
conf.host = "https://api.demo.timelight.tech"
conf.api_key["Authorization"] = "Bearer " + jwt

import_api = tlc.ImportApi(tlc.ApiClient(conf))

with open("ma-source.reference.json") as ma_source_txt:
    data = json.loads(ma_source_txt)
    import_api.v1_import_create_source_post(tlc.CreateSourceDto(data))
const TimelightApi = require("timelight-ai-js-api-client")
const fs = require("fs")

const config = { 
  basePath: "https://api.demo.timelight.tech",
  apiKey: "Bearer " + jwt,
}

const jsonTxt = fs.readFileSync('ma-source.reference.json')
const data = JSON.parse(jsonTxt);

const ImportApi = new TimelightApi.ImportApi(config);

ImportApi.v1ImportCreateSourcePost(data);
const config = {
  basePath: "https://api.demo.timelight.tech",
  apiKey: "Bearer " + jwt,
}

const ImportApi = new TimelightApi.ImportApi(config);

ImportApi.v1ImportCreateSourcePost(jsonData);
import TimelightApi from "timelight-ai-js-api-client"

const config = {
  basePath: "https://api.demo.timelight.tech",
  apiKey: "Bearer " + jwt,
}

const ImportApi = new TimelightApi.ImportApi(config);

ImportApi.v1ImportCreateSourcePost(jsonData);
$jsonTxt = file_get_contents("ma-source.reference.json");
$data = json_decode($jsonTxt, true);

$config = TimelightAi\Configuration::getDefaultConfiguration()
    ->setHost("https://api.demo.timelight.tech")
    ->setApiKey('Authorization', 'Bearer ' . $jwt);

$importApi = new TimelightAi\Api\ImportApi(new GuzzleHttp\Client(), $config);

$importApi->v1ImportCreateSourcePost(TimelightAi\Model\CreateSourceDto($data));

Ce premier import de données déclenche une analyse des profils types par le moteur IA de Timelight.

Import de données récentes

Les données récentes peuvent être ajoutées à tout moment et à plusieurs reprises à une source. Si des données étaient déjà présentes aux dates fournies, c'est la nouvelle donnée qui est utilisée. Dans la même logique, toute donnée récente ajoutée invalide les alertes non traitées de cette journée.

Chaque import de données récentes déclenche la vérification de la planification et peut donc déclencher des alertes.

{
  "sourceId": 1,
  "days": [
    {
      "date": "2016-01-01",
      "activity": [...]
    },
    {
      "date": "2016-01-02",
      "activity": [...]
    },
    // liste des journées de l'année de référence
  ]
}

Une fois ce fichier constitué, vous pourrez utiliser le point d'entrée consacré à l'import de données récentes :

curl -X POST -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${JWT}" \
     -d @ma-source.days.json \
    "${API_URL}/v1/import/days"
import timelight_ai_python_api_client as tlc

conf = tlc.Configuration()
conf.host = "https://api.demo.timelight.tech"
conf.api_key["Authorization"] = "Bearer " + jwt

import_api = tlc.ImportApi(tlc.ApiClient(conf))

with open("ma-source.days.json") as ma_source_txt:
    data = json.loads(ma_source)
    import_api.v1_import_days_post(tlc.ImportDaysDto(data))
const TimelightApi = require("timelight-ai-js-api-client")
const fs = require("fs")

const config = { 
  basePath: "https://api.demo.timelight.tech",
  apiKey: "Bearer " + jwt,
}

const jsonTxt = fs.readFileSync('ma-source.days.json')
const data = JSON.parse(jsonTxt);

const ImportApi = new TimelightApi.ImportApi(config);

ImportApi.v1ImportDaysPost(data);
const config = {
  basePath: "https://api.demo.timelight.tech",
  apiKey: "Bearer " + jwt,
}

const ImportApi = new TimelightApi.ImportApi(config);

ImportApi.v1ImportDaysPost(jsonData);
import TimelightApi from "timelight-ai-js-api-client"

const config = {
  basePath: "https://api.demo.timelight.tech",
  apiKey: "Bearer " + jwt,
}

const ImportApi = new TimelightApi.ImportApi(config);

ImportApi.v1ImportDaysPost(jsonData);
$jsonTxt = file_get_contents("ma-source.days.json");
$data = json_decode($jsonTxt, true);

$config = TimelightAi\Configuration::getDefaultConfiguration()
    ->setHost("https://api.demo.timelight.tech")
    ->setApiKey('Authorization', 'Bearer ' . $jwt);

$importApi = new TimelightAi\Api\ImportApi(new GuzzleHttp\Client(), $config);

$importApi->v1ImportDaysPost(TimelightAi\Model\ImportDaysDto($data));

Cet import de données récentes déclenche la vérification sur les alertes par rapport à la planification.