Tutorial

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

Set di dati del tutorial

Il set di dati include annotazioni di entità di località, organizzazioni, persone, tra le altre.

L'API Timeseries Insights accetta input in formato JSON. Un campione Event 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 groupId con un valore lungo per contrassegnare gli eventi correlati. Le proprietà dell'evento sono incluse come dimensions, ognuna delle quali ha un name e uno tra stringVal, boolVal, longVal o doubleVal.

Nota :le API Google Cloud accettano sia la notazione camel case (ad esempio camelCase) sia la notazione snake case (ad esempio snake_case) per i nomi dei campi JSON. La documentazione è scritta principalmente in formato camel case.

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

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

Nota :quando si legge da un'origine dati Google Cloud Storage statica, ogni evento JSON deve essere una singola riga (nota anche come formato JSON-line) 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, entrambi configurati 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 viene creato un set di dati, si trova nello stato LOADING fino al completamento dell'indicizzazione, poi 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 sul 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 esito positivo se viene accettata dal server API. Il dataset sarà nello stato LOADING fino al completamento dell'indicizzazione, dopodiché lo stato diventerà LOADED, dopo di che il dataset potrà iniziare ad accettare query e aggiornamenti, se presenti.

Nota: assicurati che il progetto disponga delle autorizzazioni di lettura appropriate per dataSources. In caso contrario, l'indicizzazione non riesce e viene restituito PERMISSION_DENIED o NOT_FOUND.

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 è 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à di streaming.

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 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 in streaming vengono indicizzati quasi in tempo reale, in modo che le modifiche possano rispondere rapidamente nei risultati di ricerca. 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 del tempo prima che i dati vengano rimossi completamente dal servizio, dopodiché List datasets non restituirà questo set di dati.