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 dérivé 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 les URL de 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 Configurer pour un accès complet.

Ensemble de données du tutoriel

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

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 le code temporel de l'événement. Il est préférable que chaque événement dispose également d'une valeur groupId longue pour marquer les événements associés. Les propriétés d'événement sont incluses en tant que dimensions, chacune ayant un name et l'un des éléments suivants : 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 la section Premiers pas.

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

Le résultat est une chaîne JSON semblable à

{
  "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 est FAILED. Les résultats incluent également les informations complètes sur l'ensemble de données de la requête de création d'origine.

Créer un ensemble de données

projects.locations.datasets.create ajoute un nouvel 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 un code d'erreur si elle est acceptée par le serveur de l'API. Le jeu de données est à l'état LOADING jusqu'à ce que l'indexation soit terminée, puis son état devient 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 effectue 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 en 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 afin que les modifications puissent être rapidement prises en compte dans les résultats de requête. Tous les événements envoyés par une seule 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 pour suppression.

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. Une fois cette opération effectuée, la liste des ensembles de données ne renverra plus cet ensemble de données.

Étape suivante

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