Usamos um pequeno conjunto de dados fornecido por Kalev Leetaru para ilustrar a API Timeseries Insights. O conjunto de dados é derivado do The GDELT Project, um banco de dados global que rastreia eventos mundiais e cobertura de mídia. Este conjunto de dados contém menções de entidades em URLs de notícias em abril de 2019.
Objetivos
- Conheça o formato de dados da API Timeseries Insights.
- Saiba como criar, consultar, atualizar e excluir conjuntos de dados.
Antes de começar
Configure um projeto do Cloud e ative a API Timeseries Insights. Siga as instruções em Configuração para acesso total.
Conjunto de dados do tutorial
O conjunto de dados inclui anotações de entidade de locais, organizações, pessoas, entre outros.
A API Timeseries Insights usa entradas no formato JSON. Um exemplo de Evento para este conjunto de dados é
{
"groupId":"-6180929807044612746",
"dimensions":[{"name":"EntityORGANIZATION","stringVal":"Medina Gazette"}],
"eventTime":"2019-04-05T08:00:00+00:00"
}
Cada evento precisa ter um campo eventTime
para o carimbo de data/hora. É preferível
que cada evento também tenha um groupId
de valor longo para marcar eventos relacionados. As propriedades do evento são incluídas como dimensions
, cada uma com um name
e uma destas: stringVal
, boolVal
, longVal
ou doubleVal
.
{"groupId":"-6180929807044612746","dimensions":[{"name":"EntityORGANIZATION","stringVal":"Medina Gazette"}],"eventTime":"2019-04-05T08:00:00+00:00"}
Listar conjuntos de dados
projects.locations.datasets.list mostra todos os conjuntos de dados em ${PROJECT_ID}
. gcurl
é um alias e
PROJECT_ID
é uma variável de ambiente, ambos configurados nos
Primeiros passos.
gcurl https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets
O resultado é uma string JSON como
{
"datasets": [
{
"name": "example",
"state": "LOADED",
...
},
{
"name": "dataset_tutorial",
"state": "LOADING",
...
}
]
}
Os resultados mostram os conjuntos de dados atualmente no projeto. O campo state
indica se o conjunto de dados está pronto para ser usado. Quando um conjunto de dados é criado,
ele permanece no estado LOADING
até que a indexação seja concluída e, em seguida, passa
para o estado LOADED
. Se ocorrer algum erro durante a criação e a indexação, ele estará no estado FAILED
. Os resultados também incluem as informações completas do conjunto de dados da solicitação de criação original.
Criar conjunto de dados
projects.locations.datasets.create adiciona um novo conjunto de dados ao projeto.
gcurl -X POST -d @create.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets
em que create.json
contém:
{
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"}
]
}
Essa solicitação cria um conjunto de dados chamado dataset_tutorial
do GCS dataSources
, que contém dados de eventos no formato JSON. Somente as dimensões listadas em dataNames
são indexadas e usadas pelo sistema.
A solicitação de criação retorna bem-sucedida se é aceita pelo servidor da API. O conjunto de dados ficará no estado LOADING
até que a indexação seja concluída. Depois, o estado se tornará LOADED
. Depois disso, o conjunto poderá começar a aceitar consultas e atualizações, se houver.
Consultar conjunto de dados
projects.locations.datasets.query executa consultas de detecção de anomalias.
gcurl -X POST -d @query.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial:query
em que query.json
contém:
{
"detectionTime": "2019-04-15T00:00:00Z",
"numReturnedSlices": 5,
"slicingParams": {
"dimensionNames": ["EntityLOCATION"]
},
"timeseriesParams": {
"forecastHistory": "1209600s",
"granularity": "86400s"
},
"forecastParams": {
"noiseThreshold": 100.0
},
}
O resultado da consulta será semelhante a este:
{
"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": {}
}
]
}
Atualização de streaming
projects.locations.datasets.appendEvents adiciona registros de eventos de modo streaming.
gcurl -X POST -d @append.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial:appendEvents
em que append.json
contém (substitua eventTime
por um carimbo de data/hora próximo ao horário atual):
{
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"
}
]
}
As atualizações transmitidas são indexadas quase em tempo real. Assim, as mudanças podem responder rapidamente nos resultados da consulta. Todos os eventos enviados por uma única solicitação projects.locations.datasets.appendEvents precisam ter o mesmo groupdId
.
Excluir conjunto de dados
projects.locations.datasets.delete marca o conjunto de dados para exclusão.
gcurl -X DELETE https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial
A solicitação é retornada imediatamente e o conjunto de dados não aceita outras consultas ou atualizações. Pode levar algum tempo até que os dados sejam completamente removidos do serviço. Depois disso, os conjuntos de dados de listas não retornarão esse conjunto de dados.
A seguir
Para encontrar outros exemplos, pesquise "API Timeseries Insights" no site do GDELT.