Tutorial

Usamos un pequeño conjunto de datos proporcionado por Kalev Leetaru para ilustrar la API Timeseries Insights. El conjunto de datos se deriva del proyecto GDELT, una base de datos global que monitoriza los eventos mundiales y la cobertura mediática. Este conjunto de datos contiene menciones de entidades en URLs de noticias de abril del 2019.

Objetivos

  • Consulta el formato de datos de la API Timeseries Insights.
  • Consulta cómo crear, consultar, actualizar y eliminar conjuntos de datos.

Antes de empezar

Configura un proyecto de Cloud y habilita la API Timeseries Insights siguiendo las instrucciones de la sección Configuración para el acceso completo.

Conjunto de datos del tutorial

El conjunto de datos incluye anotaciones de entidades de ubicaciones, organizaciones, personas y otros elementos.

La API Timeseries Insights acepta entradas en formato JSON. Un ejemplo de evento de este conjunto de datos es el siguiente:

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

Cada evento debe tener un campo eventTime para la marca de tiempo del evento. Es preferible que cada evento también tenga un groupId con un valor largo para marcar los eventos relacionados. Las propiedades de evento se incluyen como dimensions, cada una de las cuales tiene un name y uno de los siguientes valores: stringVal, boolVal, longVal o doubleVal.

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

Mostrar conjuntos de datos

projects.locations.datasets.list muestra todos los conjuntos de datos de ${PROJECT_ID}. gcurl es un alias y PROJECT_ID es una variable de entorno. Ambos se configuran en Empezar.

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

El resultado es una cadena JSON como la siguiente:

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

En los resultados se muestran los conjuntos de datos que hay en el proyecto. El campo state indica si el conjunto de datos está listo para usarse. Cuando se crea un conjunto de datos, se encuentra en el estado LOADING hasta que se completa la indexación y, a continuación, pasa al estado LOADED. Si se produce algún error durante la creación y la indexación, el estado será FAILED. Los resultados también incluyen la información completa del conjunto de datos de la solicitud de creación original.

Crear conjunto de datos

projects.locations.datasets.create añade un nuevo conjunto de datos al proyecto.

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

donde create.json contiene lo siguiente:

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

Esta solicitud crea un conjunto de datos llamado dataset_tutorial a partir de GCS dataSources, que contiene datos de eventos en formato JSON. El sistema solo indexa y usa las dimensiones que se indican en dataNames.

La solicitud de creación devuelve un mensaje de éxito si el servidor de la API la acepta. El conjunto de datos estará en estado LOADING hasta que se complete la indexación. Después, el estado cambiará a LOADED y el conjunto de datos podrá empezar a aceptar consultas y actualizaciones, si las hay.

Consultar conjunto de datos

projects.locations.datasets.query realiza consultas de detección de anomalías.

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

donde query.json contiene lo siguiente:

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

El resultado de la consulta tiene este aspecto:

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

Novedades sobre el streaming

projects.locations.datasets.appendEvents añade registros de eventos de forma continua.

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

donde append.json contiene (sustituye eventTime por una marca de tiempo cercana a la hora actual):

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

Las actualizaciones transmitidas se indexan casi en tiempo real, por lo que los cambios pueden reflejarse rápidamente en los resultados de las consultas. Todos los eventos enviados por una sola solicitud projects.locations.datasets.appendEvents deben tener el mismo groupdId.

Eliminar conjunto de datos

projects.locations.datasets.delete marca el conjunto de datos para eliminarlo.

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

La solicitud se devuelve inmediatamente y el conjunto de datos no aceptará consultas ni actualizaciones adicionales. Puede que los datos tarden un tiempo en eliminarse por completo del servicio. Después, List datasets no devolverá este conjunto de datos.

Siguientes pasos

Puedes consultar otros ejemplos en el sitio web de GDELT buscando "Timeseries Insights API".