Halaman ini diterjemahkan oleh Cloud Translation API.

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 sebutan 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 ini mencakup anotasi entity 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 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 bagian ${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 menampilkan 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, error tersebut 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.

Membuat kueri set data

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

Update streaming

projects.locations.datasets.appendEvents menambahkan kumpulan data Peristiwa dalam bentuk 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 akan diindeks secara hampir 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, Set data daftar tidak akan menampilkan set data ini.

Langkah selanjutnya

Konsep Timeseries Insights API
Pelajari REST API lebih lanjut

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