Tutorial

Kami menggunakan set data kecil yang disediakan oleh Kalev Leetaru untuk mengilustrasikan Timeseries Insights API. Set data ini berasal dari The GDELT Project, database global yang melacak peristiwa dunia dan liputan media. Set data ini berisi penyebutan entitas di URL berita pada April 2019.

Tujuan

  • Pelajari format data untuk Timeseries Insights API.
  • Pelajari cara membuat, membuat kueri, memperbarui, dan menghapus set data.

Sebelum memulai

Siapkan project Cloud dan aktifkan Timeseries Insights API dengan mengikuti Penyiapan untuk Akses Penuh.

Set data tutorial

Set data mencakup anotasi entity lokasi, organisasi, orang, dan lain-lain.

Timeseries Insights API menerima input format JSON. Contoh Peristiwa untuk set data ini adalah

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

Setiap peristiwa harus memiliki kolom eventTime untuk stempel waktu peristiwa. Setiap peristiwa sebaiknya juga memiliki groupId bernilai panjang untuk menandai peristiwa terkait. Properti peristiwa disertakan sebagai dimensions, yang masing-masing memiliki name dan salah satu dari stringVal, boolVal, longVal, atau doubleVal.

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

Mencantumkan set data

projects.locations.datasets.list menampilkan semua set data di ${PROJECT_ID}. gcurl adalah alias dan PROJECT_ID adalah variabel lingkungan, keduanya disiapkan di Memulai.

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

Hasilnya adalah string JSON seperti

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

Hasilnya akan menampilkan set data yang saat ini berada dalam project. Kolom state menunjukkan apakah set data siap digunakan. Saat baru dibuat, set data berada dalam status LOADING hingga pengindeksan selesai, lalu bertransisi ke status LOADED. Jika terjadi error selama pembuatan dan pengindeksan, statusnya akan berada dalam status FAILED. Hasilnya juga mencakup informasi set data lengkap dari permintaan pembuatan asli.

Buat set data

projects.locations.datasets.create menambahkan set data baru ke project.

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

dengan create.json berisi:

{
  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"}
  ]
}

Permintaan ini membuat set data bernama dataset_tutorial dari GCS dataSources, yang berisi data Peristiwa dalam format JSON. Hanya dimensi yang tercantum di dataNames yang diindeks dan digunakan oleh sistem.

Permintaan pembuatan akan menampilkan keberhasilan jika diterima oleh server API. Set data akan berada dalam status LOADING hingga pengindeksan selesai, lalu statusnya menjadi LOADED, setelah itu set data dapat mulai menerima kueri dan pembaruan jika ada.

Set data kueri

projects.locations.datasets.query melakukan kueri deteksi anomali.

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

dengan query.json berisi:

{
  "detectionTime": "2019-04-15T00:00:00Z",
  "numReturnedSlices": 5,
  "slicingParams": {
    "dimensionNames": ["EntityLOCATION"]
  },
  "timeseriesParams": {
    "forecastHistory": "1209600s",
    "granularity": "86400s"
  },
  "forecastParams": {
    "noiseThreshold": 100.0
  },
}

Hasil kueri akan terlihat seperti berikut:

{
  "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": {}
    }
  ]
}

Pembaruan streaming

projects.locations.datasets.appendEvents menambahkan catatan Peristiwa secara streaming.

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

dengan append.json berisi (ganti eventTime dengan stempel waktu yang mendekati waktu saat ini):

{
  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"
    }
  ]
}

Pembaruan yang di-streaming diindeks hampir secara real-time sehingga perubahan dapat merespons dengan cepat dalam hasil kueri. Semua peristiwa yang dikirim oleh satu permintaan projects.locations.datasets.appendEvents harus memiliki groupdId yang sama.

Menghapus set data

projects.locations.datasets.delete menandai set data untuk dihapus.

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

Permintaan akan segera ditampilkan, dan set data tidak akan menerima kueri atau update tambahan. Mungkin perlu waktu beberapa saat sebelum data dihapus sepenuhnya dari layanan, setelah itu, List datasets tidak akan menampilkan set data ini.

Langkah berikutnya

Contoh lainnya dapat ditemukan di situs GDELT dengan menelusuri "Timeseries Insights API".