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?
- Conceptos de la API de Timeseries Insights
- Más información sobre la API de REST
Puedes encontrar otros ejemplos en el sitio web de GDELT. Para ello, busque "Timeseries" API de Insights”.