Tutorial

Usamos um pequeno conjunto de dados fornecido por Kalev Leetaru para ilustrar a API Timeseries Insights. O conjunto de dados é derivado do Projeto GDELT (em inglês), um banco de dados global que rastreia eventos mundiais e cobertura da mídia. Esse conjunto de dados contém menções de entidades em URLs de notícias em abril de 2019.

Conjunto de dados do tutorial

O conjunto de dados inclui anotações de entidades de locais, organizações, pessoas, entre outros.

A API Timeseries Insights usa entradas no formato JSON. Um exemplo de evento para esse 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 de evento são incluídas como dimensions, cada uma com um name e um de stringVal, boolVal, longVal ou doubleVal.

Observação: as APIs do Google Cloud aceitam camel case (como camelCase) e snake case (como snake_case) para nomes de campos JSON. A documentação é escrita principalmente em camel case.

Observação :como os valores longos (números) do JSON são, na verdade, valores de ponto flutuante com apenas precisões de números inteiros, groupId e longVal são limitados a 53 dígitos binários se o JSON usar números. Para fornecer dados int64, o valor JSON precisa ser colocado entre aspas como uma string. Um groupId geralmente é um ID numérico ou gerado com uma função de hash determinística, atendendo à restrição acima.

Observação: o campo name deve ter valores alfanuméricos incluindo '_'. Caracteres especiais, incluindo o espaço, não são aceitos. O campo stringVal aceita caracteres Unicode válidos.

Observação: ao ler de uma fonte de dados estática do Google Cloud Storage, cada evento JSON precisa ser uma única linha (também conhecido como formato JSON-line), da seguinte forma:

{"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 em 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 no projeto. O campo state indica se o conjunto de dados está pronto para uso. Quando um conjunto de dados é criado, ele fica no estado LOADING até que a indexação seja concluída. Depois, ele passa para o estado LOADED. Se ocorrerem erros durante a criação e a indexação, o estado será 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 sucesso se for aceita pelo servidor da API. O conjunto de dados vai ficar no estado LOADING até que a indexação seja concluída. Depois, o estado muda para LOADED, e o conjunto de dados pode começar a aceitar consultas e atualizações, se houver.

Observação: verifique se o projeto tem as permissões de leitura adequadas para dataSources. Caso contrário, a indexação falhará com PERMISSION_DENIED ou NOT_FOUND.

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 é 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 maneira contínua.

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 momento 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 mudanças possam 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 retorna 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, "List datasets" não vai retornar esse conjunto de dados.