Instructivo

Usamos un conjunto de datos pequeño proporcionado por Kalev Leetaru para ilustrar la serie temporal la API de Insights. El conjunto de datos se deriva de El proyecto GDELT, una base de datos global para realizar un seguimiento de acontecimientos mundiales y cobertura de los medios de comunicación. Este conjunto de datos contiene menciones de entidades en URLs de noticias en abril de 2019.

Objetivos

  • Conoce el formato de datos para la API de Timeseries Insights.
  • Aprende a crear, consultar, actualizar y borrar conjuntos de datos.

Antes de comenzar

Configura un proyecto de Cloud y habilita la API de Timeseries Insights Configura el Acceso total.

Conjunto de datos del instructivo

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

La API de Timeseries Insights toma entradas en formato JSON. Una muestra Evento 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. Es preferible cada evento también tiene un groupId de larga duración para marcar eventos relacionados. Evento se incluyen como dimensions, cada una de las cuales tiene un valor de 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 Cómo comenzar.

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

El resultado es una cadena JSON como

{
  "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 un conjunto de datos es tan solo creado, permanecerá en el estado LOADING hasta que se complete la indexación y, luego, al estado LOADED. Si se produce algún error durante la creación y la indexación, se 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 agrega 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 de GCS dataSources, que contienen datos de eventos en formato JSON. Solo se muestran las dimensiones en dataNames se indexan y usan en el sistema.

La solicitud de creación muestra el resultado de forma 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; luego, el estado se convierte en LOADED, después de lo cual el conjunto de datos puede comenzar a aceptar consultas. actualizaciones, si las hubiera.

Conjunto de datos de consulta

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 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 la transmisión

projects.locations.datasets.appendEvents agrega registros de eventos por transmisión.

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 en los resultados de la consulta. Todos los eventos enviados por un projects.locations.datasets.appendEvents debe tener el mismo groupdId.

Borrar conjunto de datos

projects.locations.datasets.delete marca el conjunto de datos para su eliminación.

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 o actualizaciones. Es posible que los datos demoren un tiempo en quitarse por completo del servicio. Después de eso, Enumerar conjuntos de datos no mostrará este conjunto de datos.

¿Qué sigue?

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