Tutorial

---

Utilizziamo un piccolo set di dati fornito da Kalev Leetaru per illustrare l'API Timeseries Insights. Il set di dati deriva da The GDELT Project, un database globale che monitora eventi mondiali e copertura mediatica. Questo set di dati contiene menzioni di entità in URL di notizie nell'aprile 2019.

Obiettivi

• Scopri il formato dei dati per l'API Timeseries 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 come segue Configurazione per l'Accesso completo.

Set di dati del tutorial

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

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 ogni evento ha anche un groupId di valore lungo per contrassegnare gli eventi correlati. Evento sono incluse come dimensions, ognuna delle quali ha un name e uno di stringVal, boolVal, longVal o doubleVal.

Nota: le API Google Cloud accettano sia camel case (come camelCase) che snake (come snake_case) per i nomi dei campi JSON. La documentazione è per lo più scritto come "caml case".

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

Nota: il campo name deve essere alfanumerico tra cui '_'. I caratteri speciali, incluso lo spazio, non sono supportati. Il campo stringVal supporta caratteri Unicode validi.

Nota: quando leggi da un'origine dati Google Cloud Storage statica ogni file JSON dovrebbe essere una singola riga (noto anche come formato riga JSON), come segue:

{"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 simile a

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

I risultati mostrano i set di dati attualmente all'interno del progetto. Il campo state indica se il set di dati è pronto per essere utilizzato. Quando un set di dati è creato, lo stato rimane LOADING fino al completamento dell'indicizzazione, quindi le transizioni allo stato LOADED. Se si verificano errori durante la creazione e l'indicizzazione, nello stato 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, che contiene dati sugli eventi in formato JSON. Sono elencate solo le dimensioni in dataNames vengono indicizzati e utilizzati dal sistema.

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

Nota: assicurati che il progetto disponga delle autorizzazioni di lettura appropriate per dataSources. In caso contrario, l'indicizzazione non andrà 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 è 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 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 vicino a quello 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 in streaming vengono indicizzati quasi in tempo reale, in modo che le modifiche possano rispondere rapidamente i risultati della 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à query o aggiornamenti. 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.

Puoi trovare altri esempi su il sito web di GDELT cercando "Timeseries" l'API Insights".