Esta página foi traduzida pela API Cloud Translation.

Tutorial

Usamos um pequeno conjunto de dados fornecido por Kalev Leetaru para ilustrar a API Timeseries Insights. O conjunto de dados é derivado do GDELT Project, uma base de dados global que acompanha eventos mundiais e cobertura mediática. Este conjunto de dados contém menções de entidades em URLs de notícias em abril de 2019.

Objetivos

Saiba qual é o formato de dados da API Timeseries Insights.
Saiba como criar, consultar, atualizar e eliminar conjuntos de dados.

Antes de começar

Configure um projeto do Google Cloud e ative a API Timeseries Insights seguindo as instruções em Configuração para acesso total.

Conjunto de dados do tutorial

O conjunto de dados inclui anotações de entidades de localizações, organizações, pessoas, entre outras.

A API Timeseries Insights aceita 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 tem de ter um campo eventTime para a data/hora do evento. É preferível que cada evento também tenha um groupId de valor longo para marcar eventos relacionados. As propriedades dos eventos são incluídas como dimensions, cada uma com um name e um dos seguintes: stringVal, boolVal, longVal ou doubleVal.

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

Liste 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 em Introdução.

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 a ser usado. Quando um conjunto de dados é criado, encontra-se no estado LOADING até a indexação ser concluída e, em seguida, passa para o estado LOADED. Se ocorrerem erros durante a criação e a indexação, o estado é FAILED. Os resultados também incluem as informações completas do conjunto de dados do pedido de criação original.

Crie um 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"}
  ]
}

Este pedido cria um conjunto de dados denominado dataset_tutorial a partir do GCS dataSources, que contém dados de eventos no formato JSON. Apenas as dimensões indicadas em dataNames são indexadas e usadas pelo sistema.

O pedido de criação devolve êxito se for aceite pelo servidor da API. O conjunto de dados vai estar no estado LOADING até a indexação ser concluída. Em seguida, o estado passa a LOADED, após o qual o conjunto de dados pode começar a aceitar consultas e atualizações, se existirem.

Consultar conjunto de dados

projects.locations.datasets.query executa consultas de deteçã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 tem o seguinte aspeto:

{
  "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 registos de eventos de forma contínua.

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

onde append.json contém (substitua eventTime por uma indicação de tempo próxima da hora 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 para que as alterações possam responder rapidamente nos resultados da consulta. Todos os eventos enviados por um único pedido projects.locations.datasets.appendEvents têm de ter o mesmo groupdId.

Elimine o conjunto de dados

projects.locations.datasets.delete marca o conjunto de dados para eliminação.

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

O pedido é devolvido imediatamente e o conjunto de dados não aceita consultas nem atualizações adicionais. Pode demorar algum tempo até que os dados sejam completamente removidos do serviço. Após a remoção, os conjuntos de dados de listas não devolvem este conjunto de dados.

O que se segue?

Conceitos da API Timeseries Insights
Saiba mais sobre a API REST

Pode encontrar outros exemplos no Website do GDELT pesquisando "API Timeseries Insights".