Instructivo

Usamos un pequeño conjunto de datos proporcionado por Kalev Leetaru para ilustrar la API de Timeseries Insights. El conjunto de datos proviene de The GDELT Project, una base de datos global que hace un seguimiento de los eventos mundiales y la cobertura de los medios. Este conjunto de datos contiene menciones de entidades en las URLs de noticias de abril de 2019.

Objetivos

  • Obtén información sobre el formato de datos de la API de Timeseries Insights.
  • Obtén información para crear, consultar, actualizar y borrar conjuntos de datos.

Antes de comenzar

Configura un proyecto de Cloud y habilita la API de Timeseries Insights siguiendo la configuración para obtener acceso completo.

Conjunto de datos del instructivo

El conjunto de datos incluye anotaciones de entidades de ubicaciones, organizaciones, personas y mucho más.

La API de Timeseries Insights acepta entradas en formato JSON. Un Evento de muestra para este conjunto de datos es

{
  "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. Se prefiere que cada evento también tenga un groupId de valor largo para marcar eventos relacionados. Las propiedades del evento se incluyen como dimensions, cada una de las cuales tiene un name y uno de stringVal, boolVal, longVal o doubleVal.

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

Mostrar lista de conjuntos de datos

projects.locations.datasets.list muestra todos los conjuntos de datos en ${PROJECT_ID}. gcurl es un alias y PROJECT_ID es una variable de entorno, ambas configuradas en Introducción.

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",
      ...
    }
  ]
}

Los resultados muestran los conjuntos de datos que se encuentran actualmente 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 el indexado y, luego, pasa al estado LOADED. Si se producen errores durante la creación y el indexado, estará en el estado 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 conjunto de datos nuevo al proyecto.

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

En el ejemplo anterior, 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 de GCS dataSources, que contiene datos de eventos en formato JSON. Solo las dimensiones que se enumeran en dataNames se indexan y usan en el sistema.

La solicitud de creación se muestra como correcta si el servidor de la API la acepta. El conjunto de datos estará en el estado LOADING hasta que se complete la indexación, y luego el estado cambiará a LOADED. Después de eso, el conjunto de datos podrá comenzar a aceptar consultas y actualizaciones, si las hay.

Consulta el 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

En el ejemplo anterior, 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 se ve de la siguiente manera:

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

Actualización de transmisión

projects.locations.datasets.appendEvents agrega 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 (reemplaza 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 para que los cambios puedan responder rápidamente en los resultados de las consultas. Todos los eventos que envía una sola solicitud projects.locations.datasets.appendEvents deben tener el mismo groupdId.

Borrar conjunto de datos

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

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

La solicitud se muestra de inmediato, y el conjunto de datos no aceptará consultas ni actualizaciones adicionales. Es posible que debas esperar un tiempo hasta que los datos se quiten por completo del servicio. Después de eso, los conjuntos de datos de List no mostrarán este conjunto de datos.

¿Qué sigue?

Puedes encontrar otros ejemplos en el sitio web de GDELT. Para ello, busca "API de Timeseries Insights".