Cette page a été traduite par l'API Cloud Translation.

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 de Le projet GDELT, un outil mondial de suivi des bases de données les événements mondiaux et la couverture médiatique. Cet ensemble de données contient des mentions d'entités dans URL Google Actualités en avril 2019.

Objectifs

Découvrez le format de données pour 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 Configurer l'accès complet

Ensemble de données du tutoriel

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

L'API Timeseries Insights accepte des entrées au format JSON. Exemple É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 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. PROJECT_ID est une variable d'environnement, toutes deux configurées dans 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 montrent les ensembles de données actuellement inclus dans le projet. Le champ state indique si l'ensemble de données est prêt à être utilisé. Lorsqu’un jeu de données est juste est à l'état LOADING jusqu'à la fin de l'indexation, puis passe à l'état suivant : à 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 contiennent des données d'événement au format JSON. Seules les dimensions listées dans dataNames sont indexés et utilisés par le système.

La requête de création renvoie un résultat positif si elle est acceptée par le serveur d'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 l'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 ressemble à ceci:

{
  "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 sous forme de flux.

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 par flux sont indexées en temps quasi réel afin que les modifications puissent s'adapter rapidement les résultats de la requête. Tous les événements envoyés par un même projects.locations.datasets.appendEvents doit avoir le même groupdId.

Supprimer un ensemble de données

projects.locations.datasets.delete marque l'ensemble de données à supprimer.

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

Concepts de l'API Timeseries Insights
En savoir plus sur l'API REST

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