Se usó la API de Cloud Translation para traducir esta página.

Instructivo

Usamos un pequeño conjunto de datos proporcionado por Kalev Leetaru para ilustrar la API de Timeseries Insights. El conjunto de datos se deriva de The GDELT Project, una base de datos global que hace un seguimiento de los eventos mundiales y la cobertura de los medios. Este conjunto de datos contiene menciones de entidades en URLs de noticias en abril de 2019.

Objetivos

Conoce el formato de datos de 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 siguiendo los pasos de la Configuración para acceso completo.

Conjunto de datos del instructivo

El conjunto de datos incluye anotaciones de entidades de ubicaciones, organizaciones, personas, entre otras.

La API de Timeseries Insights toma entradas en formato JSON. Un ejemplo de un objeto Event para este conjunto de datos es el siguiente:

{
  "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. Se prefiere que cada evento también tenga un groupId con un valor largo para marcar los eventos relacionados. Las propiedades del evento se incluyen como dimensions, cada una de las cuales tiene un 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, ambos configurados en 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",
      ...
    }
  ]
}

En los resultados, se 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 se crea un conjunto de datos, se encuentra en el estado LOADING hasta que se completa la indexación y, luego, pasa al estado LOADED. Si se producen errores durante la creación y la indexación, estará en 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

En el ejemplo anterior, 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 a partir de dataSources de GCS, que contiene datos de eventos en formato JSON. Solo las dimensiones que se indican en dataNames se indexan y se usan en el sistema.

La solicitud de creación muestra un mensaje de éxito si el servidor de la API la acepta. El conjunto de datos estará en estado LOADING hasta que se complete la indexación. Luego, el estado cambiará a LOADED, y el conjunto de datos podrá comenzar a aceptar consultas y actualizaciones, si las hay.

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

En el ejemplo anterior, 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 transmisión

projects.locations.datasets.appendEvents agrega registros de eventos de forma continua.

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

donde append.json contiene lo siguiente (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, por lo que los cambios pueden responder rápidamente en los resultados de la búsqueda. Todos los eventos enviados por una sola solicitud de projects.locations.datasets.appendEvents deben 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 devuelve de inmediato, y el conjunto de datos no aceptará consultas ni actualizaciones adicionales. Es posible que transcurra un tiempo antes de que los datos se quiten por completo del servicio, después de lo cual List datasets no devolverá este conjunto de datos.

¿Qué sigue?

Conceptos de la API de Timeseries Insights
Obtén más información sobre la API de REST

Puedes encontrar otros ejemplos en el sitio web de GDELT buscando "API de Timeseries Insights".