Questa pagina è stata tradotta dall'API Cloud Translation.

Tutorial

Utilizziamo un piccolo set di dati fornito da Kalev Leetaru per illustrare l'API Timeseries Insights. Il set di dati è derivato dal progetto GDELT, un database globale che monitora gli eventi mondiali e la copertura mediatica. Questo set di dati contiene menzioni di entità negli URL delle notizie di aprile 2019.

Obiettivi

Scopri il formato dei dati per l'API Timeseries Insights.
Scopri come creare, eseguire query, aggiornare ed eliminare i set di dati.

Prima di iniziare

Configura un progetto Cloud e abilita l'API Timeseries Insights seguendo la sezione Configurazione per l'accesso completo.

Set di dati del tutorial

Il set di dati include annotazioni di entità di località, organizzazioni, persone e altro ancora.

L'API Timeseries Insights accetta input in formato JSON. Un evento di esempio per questo set di dati è

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

Ogni evento deve avere un campo eventTime per il timestamp dell'evento. È preferibile che ogni evento abbia anche un valore lungo groupId per contrassegnare gli eventi correlati. Le proprietà eventi sono incluse come dimensions, ognuna delle quali ha un name e uno tra stringVal, boolVal, longVal o doubleVal.

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

Elenca set di dati

projects.locations.datasets.list mostra tutti i set di dati in ${PROJECT_ID}. gcurl è un alias e PROJECT_ID è una variabile di ambiente, entrambe configurate in Guida introduttiva.

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

Il risultato è una stringa JSON come

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

I risultati mostrano i set di dati attualmente nel progetto. Il campo state indica se il set di dati è pronto per essere utilizzato. Quando un set di dati viene appena creato, è nello stato LOADING fino al completamento dell'indicizzazione, quindi passa allo stato LOADED. Se si verificano errori durante la creazione e l'indicizzazione, lo stato sarà FAILED. I risultati includono anche le informazioni complete del set di dati dalla richiesta di creazione originale.

Crea set di dati

projects.locations.datasets.create aggiunge un nuovo set di dati al progetto.

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

dove create.json contiene:

{
  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"}
  ]
}

Questa richiesta crea un set di dati denominato dataset_tutorial da GCS dataSources, contenente dati sugli eventi in formato JSON. Solo le dimensioni elencate in dataNames vengono indicizzate e utilizzate dal sistema.

La richiesta di creazione restituisce il risultato positivo se viene accettata dal server API. Il set di dati sarà in stato LOADING fino al completamento dell'indicizzazione, poi lo stato diventa LOADED, dopodiché il set di dati può iniziare ad accettare query e eventuali aggiornamenti.

Set di dati di query

projects.locations.datasets.query esegue query di rilevamento delle anomalie.

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

dove query.json contiene:

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

Il risultato della query è il seguente:

{
  "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": {}
    }
  ]
}

Aggiornamento in streaming

projects.locations.datasets.appendEvents aggiunge record di eventi in streaming.

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

dove append.json contiene (sostituire eventTime con un timestamp vicino all'ora corrente):

{
  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"
    }
  ]
}

Gli aggiornamenti in streaming vengono indicizzati quasi in tempo reale, in modo che le modifiche possano essere applicate rapidamente nei risultati delle query. Tutti gli eventi inviati da una singola richiesta projects.locations.datasets.appendEvents devono avere lo stesso groupdId.

Elimina set di dati

projects.locations.datasets.delete contrassegni il set di dati per l'eliminazione.

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

La richiesta viene restituita immediatamente e il set di dati non accetterà query o aggiornamenti aggiuntivi. Potrebbero essere necessari alcuni istanti prima che i dati vengano rimossi completamente dal servizio, dopodiché l'elenco dei set di dati non restituirà questo set di dati.

Passaggi successivi

Concetti dell'API Timeseries Insights
Scopri di più sull'API REST

Altri esempi sono disponibili sul sito web di GDELT cercando "API Timeseries Insights".