Tutorial

---

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

Obiettivi

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

Prima di iniziare

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

Set di dati tutorial

Il set di dati include annotazioni di entità relative a località, organizzazioni, persone tra gli altri.

L'API Timeseries Insights utilizza 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 groupId di valore lungo per contrassegnare gli eventi correlati. Le proprietà evento sono incluse come dimensions, ognuna delle quali ha un name e una tra stringVal, boolVal, longVal o doubleVal.

Nota: le API Google Cloud accettano entrambe le custodie camel (come camelCase) e snake (come snake_case) per i nomi dei campi JSON. La documentazione è per lo più scritta con lettere maiuscole e minuscole.

Nota: poiché i valori JSON lunghi (numeri) sono in realtà valori in virgola mobile con solo precisioni numeriche, sia groupId che longVal sono limitati a 53 cifre binarie se JSON utilizza i numeri. Per fornire i dati int64, il valore JSON deve essere citato come una stringa. Un groupId è in genere un ID numerico o generato con una funzione hash deterministica, soddisfacendo la limitazione di cui sopra.

Nota: il campo name dovrebbe contenere valori alfanumerici, tra cui '_'. I caratteri speciali, incluso lo spazio, non sono supportati. Il campo stringVal supporta caratteri Unicode validi.

Nota: durante la lettura da un'origine dati statica di Google Cloud Storage, ogni evento JSON deve essere costituito da una singola riga (noto anche come formato a riga JSON), come segue:

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

Creazione di un elenco di 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, entrambi impostati 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 presenti nel progetto. Il campo state indica se il set di dati è pronto per essere utilizzato. Quando un set di dati è appena stato creato, lo stato rimane 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 della 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, che contiene dati sugli eventi in formato JSON. Solo le dimensioni elencate in dataNames vengono indicizzate e utilizzate dal sistema.

La richiesta di creazione restituisce un errore se viene accettata dal server API. Il set di dati sarà in stato LOADING fino al completamento dell'indicizzazione, dopodiché lo stato diventerà LOADED. Trascorso questo periodo, il set di dati può iniziare ad accettare query ed eventuali aggiornamenti.

Nota: assicurati che il progetto disponga delle autorizzazioni di lettura appropriate per dataSources. In caso contrario, l'indicizzazione non va a buon fine con PERMISSION_DENIED o NOT_FOUND.

Set di dati di query

projects.locations.datasets.query esegue query per il rilevamento di 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 è simile al 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 dello streaming

projects.locations.datasets.appendEvents aggiunge record di eventi in modalità flusso.

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

dove append.json contiene (sostituisci eventTime con un timestamp prossimo all'ora attuale):

{
  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 trasmessi vengono indicizzati quasi in tempo reale, in modo che le modifiche possano rispondere 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 contrassegna 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à ulteriori query o aggiornamenti. Potrebbe essere necessario un po' di tempo 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 sull'API Timeeries Insights
• Scopri di più sull'API REST

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