Tutoriel

Nous utilisons un petit ensemble de données fourni par Kalev Leetaru pour illustrer l'API Timeseries Insights. L'ensemble de données est issu du projet GDELT, une base de données mondiale qui suit les événements mondiaux et la couverture médiatique. Cet ensemble de données contient des mentions d'entités dans des URL d'actualités en avril 2019.

Objectifs

  • Découvrez le format de données de l'API Timeseries Insights.
  • Découvrez comment créer, interroger, mettre à jour et supprimer des ensembles de données.

Avant de commencer

Configurez un projet Cloud et activez l'API Timeseries Insights en suivant la procédure de configuration pour un accès complet.

Ensemble de données du tutoriel

L'ensemble de données inclut des annotations d'entités de lieux, d'organisations, de personnes, entre autres.

L'API Timeseries Insights accepte les entrées au format JSON. Voici un exemple d'événement pour cet ensemble de données :

{
  "groupId":"-6180929807044612746",
  "dimensions":[{"name":"EntityORGANIZATION","stringVal":"Medina Gazette"}],
  "eventTime":"2019-04-05T08:00:00+00:00"
}

Chaque événement doit comporter un champ eventTime pour l'horodatage de l'événement. Il est préférable que chaque événement comporte également un groupId de valeur longue pour marquer les événements associés. Les propriétés des événements sont incluses en tant que dimensions, chacune ayant un name et l'une des valeurs suivantes : stringVal, boolVal, longVal ou doubleVal.

{"groupId":"-6180929807044612746","dimensions":[{"name":"EntityORGANIZATION","stringVal":"Medina Gazette"}],"eventTime":"2019-04-05T08:00:00+00:00"}

Répertorier des ensembles de données

projects.locations.datasets.list affiche tous les ensembles de données sous ${PROJECT_ID}. gcurl est un alias et PROJECT_ID est une variable d'environnement, tous deux configurés dans Premiers pas.

gcurl https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets

Le résultat est une chaîne JSON telle que

{
  "datasets": [
    {
      "name": "example",
      "state": "LOADED",
      ...
    },
    {
      "name": "dataset_tutorial",
      "state": "LOADING",
      ...
    }
  ]
}

Les résultats affichent les ensembles de données actuellement associés au projet. Le champ state indique si l'ensemble de données est prêt à être utilisé. Lorsqu'un ensemble de données vient d'être créé, il est à l'état LOADING jusqu'à ce que l'indexation soit terminée, puis passe à l'état LOADED. Si des erreurs se produisent lors de la création et de l'indexation, l'état FAILED s'affiche. Les résultats incluent également les informations complètes sur l'ensemble de données issues de la demande de création d'origine.

Créer un ensemble de données

projects.locations.datasets.create ajoute un ensemble de données au projet.

gcurl -X POST -d @create.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets

où create.json contient :

{
  name: "dataset_tutorial",
  dataNames: [
    "EntityCONSUMER_GOOD",
    "EntityEVENT",
    "EntityLOCATION",
    "EntityORGANIZATION",
    "EntityOTHER",
    "EntityPERSON",
    "EntityUNKNOWN",
    "EntityWORK_OF_ART",
  ],
  dataSources: [
    {uri: "gs://data.gdeltproject.org/blog/2021-timeseries-insights-api/datasets/webnlp-201904.json"}
  ]
}

Cette requête crée un ensemble de données nommé dataset_tutorial à partir de GCS dataSources, qui contient des données d'événement au format JSON. Seules les dimensions listées dans dataNames sont indexées et utilisées par le système.

La requête de création renvoie une réponse positive si elle est acceptée par le serveur de l'API. L'état du jeu de données est LOADING jusqu'à ce que l'indexation soit terminée, puis il passe à LOADED. Le jeu de données peut alors commencer à accepter les requêtes et les mises à jour, le cas échéant.

Interroger un ensemble de données

projects.locations.datasets.query exécute des requêtes de détection d'anomalies.

gcurl -X POST -d @query.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial:query

où query.json contient :

{
  "detectionTime": "2019-04-15T00:00:00Z",
  "numReturnedSlices": 5,
  "slicingParams": {
    "dimensionNames": ["EntityLOCATION"]
  },
  "timeseriesParams": {
    "forecastHistory": "1209600s",
    "granularity": "86400s"
  },
  "forecastParams": {
    "noiseThreshold": 100.0
  },
}

Le résultat de la requête se présente comme suit :

{
  "name": "projects/timeseries-staging/locations/us-central1/datasets/webnlp-201901-202104-dragosd",
  "slices": [
    {
      "dimensions": [
        {
          "name": "EntityLOCATION",
          "stringVal": "Notre Dame"
        }
      ],
      "detectionPointActual": 1514,
      "detectionPointForecast": 15.5,
      "expectedDeviation": 5.5,
      "anomalyScore": 14.203791469194313,
      "status": {}
    },
    {
      "dimensions": [
        {
          "name": "EntityLOCATION",
          "stringVal": "Seine"
        }
      ],
      "detectionPointActual": 1113,
      "detectionPointForecast": 14,
      "expectedDeviation": 15,
      "anomalyScore": 9.5565217391304351,
      "status": {}
    },
    {
      "dimensions": [
        {
          "name": "EntityLOCATION",
          "stringVal": "Ile de la Cite"
        }
      ],
      "detectionPointActual": 852,
      "detectionPointForecast": 0,
      "expectedDeviation": 1,
      "anomalyScore": 8.435643564356436,
      "status": {}
    },
    {
      "dimensions": [
        {
          "name": "EntityLOCATION",
          "stringVal": "Paris"
        }
      ],
      "detectionPointActual": 1461,
      "detectionPointForecast": 857,
      "expectedDeviation": 441,
      "anomalyScore": 1.1164510166358594,
      "status": {}
    },
    {
      "dimensions": [
        {
          "name": "EntityLOCATION",
          "stringVal": "France"
        }
      ],
      "detectionPointActual": 1098,
      "detectionPointForecast": 950.5,
      "expectedDeviation": 476.5,
      "anomalyScore": 0.25585429314830876,
      "status": {}
    }
  ]
}

Mise à jour du streaming

projects.locations.datasets.appendEvents ajoute des enregistrements d'événements en streaming.

gcurl -X POST -d @append.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial:appendEvents

où append.json contient (veuillez remplacer eventTime par un code temporel proche de l'heure actuelle) :

{
  events: [
    {
      "groupId":"1324354349507023708",
      "dimensions":[{"name":"EntityPERSON","stringVal":"Jason Marsalis"}],
      "eventTime":"2022-02-16T15:45:00+00:00"
    },{
      "groupId":"1324354349507023708",
      "dimensions":[{"name":"EntityORGANIZATION","stringVal":"WAFA"}],
      "eventTime":"2022-02-16T04:00:00+00:00"
    }
  ]
}

Les mises à jour en streaming sont indexées presque en temps réel, ce qui permet aux modifications d'être rapidement reflétées dans les résultats des requêtes. Tous les événements envoyés par une même requête projects.locations.datasets.appendEvents doivent avoir le même groupdId.

Supprimer un ensemble de données

projects.locations.datasets.delete marque l'ensemble de données comme devant être supprimé.

gcurl -X DELETE https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial

La requête est renvoyée immédiatement, et l'ensemble de données n'accepte pas de requêtes ni de mises à jour supplémentaires. Il peut s'écouler un certain temps avant que les données ne soient complètement supprimées du service. Après cela, la méthode List datasets ne renverra plus cet ensemble de données.

Étapes suivantes

Vous trouverez d'autres exemples sur le site Web de GDELT en recherchant "Timeseries Insights API".