Kami menggunakan set data kecil yang disediakan oleh Kalev Leetaru untuk mengilustrasikan Timeseries Insights API. Set data berasal dari The GDELT Project, sebuah database global yang melacak peristiwa di dunia dan liputan media. Set data ini berisi penyebutan entitas di URL berita pada April 2019.
Tujuan
- Pelajari format data untuk Timeseries Insights API.
- Mempelajari cara membuat, mengkueri, memperbarui, dan menghapus set data.
Sebelum memulai
Siapkan project Cloud dan aktifkan Timeseries Insights API setelah mengikuti Penyiapan untuk Akses Penuh.
Set data tutorial
Set data mencakup anotasi entity untuk lokasi, organisasi, orang, dan lainnya.
Timeseries Insights API menggunakan 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. Sebaiknya
setiap peristiwa juga memiliki groupId yang bernilai lama 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 pada ${PROJECT_ID}. gcurl adalah alias dan
PROJECT_ID adalah variabel lingkungan, yang keduanya disiapkan di
Memulai.
gcurl https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets
Hasilnya adalah {i>string<i} JSON seperti
{
"datasets": [
{
"name": "example",
"state": "LOADED",
...
},
{
"name": "dataset_tutorial",
"state": "LOADING",
...
}
]
}
Hasilnya menunjukkan set data yang saat ini berada dalam project. Kolom state
menunjukkan apakah set data siap digunakan. Saat baru saja dibuat, set data akan berada dalam status LOADING hingga pengindeksan selesai, lalu bertransisi ke status LOADED. Jika terjadi error selama pembuatan dan pengindeksan, status tersebut akan berupa FAILED. Hasilnya juga mencakup informasi {i>dataset<i} yang lengkap
dari permintaan pembuatan asli.
Membuat 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 dataSources GCS, yang berisi data Peristiwa dalam format JSON. Hanya dimensi yang tercantum dalam dataNames yang diindeks dan digunakan oleh sistem.
Permintaan pembuatan 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 diperbarui, jika ada.
Set data kueri
projects.locations.datasets.query menjalankan 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 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": {}
}
]
}
Update streaming
projects.locations.datasets.appendEvents menambahkan data 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 sekarang):
{
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"
}
]
}
Update 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 pembaruan tambahan. Mungkin perlu waktu beberapa saat sebelum data dihapus sepenuhnya dari layanan, setelah itu set data Daftar tidak akan menampilkan set data ini.
Langkah selanjutnya
Beberapa contoh lain dapat ditemukan di situs GDELT dengan menelusuri "TimeseriesInsights API".