Esta página foi traduzida pela API Cloud Translation.

Tutorial

Usamos um pequeno conjunto de dados fornecido pelo Kalev Leetaru para ilustrar as séries temporais API Insights. O conjunto de dados é derivado O projeto GDELT, um projeto global de acompanhamento de banco de dados eventos mundiais e cobertura na mídia. Este conjunto de dados contém referências a entidades 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 seguindo a 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 aceita 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 cada evento também tem 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 um dos 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 configurada Como começar.

gcurl https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets

O resultado é uma string JSON como esta:

{
  "datasets": [
    {
      "name": "example",
      "state": "LOADED",
      ...
    },
    {
      "name": "dataset_tutorial",
      "state": "LOADING",
      ...
    }
  ]
}

Os resultados mostram os conjuntos de dados que estão no projeto. O campo state indica se o conjunto de dados está pronto para uso. Quando um conjunto de dados está criado, ele fica no estado LOADING até que a indexação seja concluída e, em seguida, faz a transição. para o estado LOADED. Se ocorrer algum erro 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"}
  ]
}

Esta solicitação cria um conjunto de dados chamado dataset_tutorial no 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 retornará sucesso se for aceita pelo servidor da API. O O conjunto de dados ficará no estado LOADING até que a indexação seja concluída, então o estado se torna LOADED, depois do qual o conjunto de dados pode 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 evento 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 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 alterações possam responder rapidamente em resultados da consulta. Todos os eventos enviados por um único projects.locations.datasets.appendEvents solicitação 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, Listar conjuntos de dados não retornará esse conjunto de dados.

A seguir

Conceitos da API temporals Insights
Saiba mais sobre a API REST.

Outros exemplos podem ser encontrados na no site do GDELT pesquisando "Timeseries API Insights".