Usamos un conjunto de datos pequeño que proporciona Kalev Leetaru para ilustrar la API de Timeseries Insights. El conjunto de datos se deriva del proyecto GDELT, una base de datos global que realiza un seguimiento de los eventos mundiales y la cobertura de medios. Este conjunto de datos contiene menciones de entidades en las URLs de noticias en abril de 2019.
Objetivos
- Aprende 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 después de la configuración para acceso total.
Conjunto de datos del instructivo
El conjunto de datos incluye anotaciones de entidades de ubicaciones, organizaciones y personas, entre otras.
La API de Timeseries Insights toma 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 largo valor 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 que se encuentra configurada en la sección 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 se acaba de crear un conjunto de datos, se encuentra en el estado LOADING hasta que se completa la indexación y, luego, pasa al estado LOADED. Si se produce algún error durante la creación y la indexación, estará en 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 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"}
]
}
Con esta solicitud, se crea un conjunto de datos llamado dataset_tutorial desde dataSources de GCS, que contiene datos de eventos en formato JSON. El sistema solo indexa y usa las dimensiones que se muestran en dataNames.
La solicitud de creación muestra el resultado correcto 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 convertirá en LOADED. Luego, el conjunto de datos podrá comenzar a aceptar consultas y 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
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 las transmisiones
projects.locations.datasets.appendEvents agrega registros de eventos en forma de 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 al momento 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, de modo que los cambios puedan responder rápidamente en los resultados de la consulta. Todos los eventos enviados por 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 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 ni actualizaciones adicionales. Puede pasar un tiempo hasta que los datos se quiten por completo del servicio, después de lo cual 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 si buscas "API de Timeseries Insights".