튜토리얼

Kalev Leetaru가 제공하는 작은 데이터 세트를 사용하여 Timeseries Insights API를 실제로 보여줍니다. 데이터 세트는 세계적인 이벤트 및 미디어 노출 범위를 추적하는 글로벌 데이터베이스인 GDELT 프로젝트에서 얻습니다. 이 데이터 세트에는 2019년 4월 뉴스 URL에서 언급된 항목이 포함되어 있습니다.

목표

Timeseries Insights API의 데이터 형식을 알아봅니다.
데이터 세트를 생성, 쿼리, 업데이트, 삭제하는 방법을 알아봅니다.

시작하기 전에

Cloud 프로젝트를 설정하고 전체 액세스 설정에 따라 Timeseries Insights API를 사용 설정합니다.

튜토리얼 데이터 세트

데이터 세트에는 위치, 조직, 사람에 대한 항목 주석이 포함되어 있습니다.

Timeseries Insights API에는 JSON 형식 입력이 사용됩니다. 이 데이터 세트의 샘플 이벤트는 다음과 같습니다.

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

각 이벤트에는 이벤트 타임스탬프에 해당하는 eventTime 필드가 있어야 합니다. 각 이벤트에 관련 이벤트를 표시하는 긴 값의 groupId도 포함하는 것이 좋습니다. 이벤트 속성은 dimensions(으)로 포함되며, 각 속성에는 name와 stringVal, boolVal, longVal, doubleVal 중 하나가 포함됩니다.

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

데이터 세트 나열

projects.locations.datasets.list는 ${PROJECT_ID} 아래 모든 데이터 세트를 표시합니다. gcurl은(는) 별칭이고 PROJECT_ID은(는) 환경 변수로 둘 모두 시작하기에서 설정되었습니다.

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

결과는 다음과 같은 JSON 문자열입니다.

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

결과에는 현재 프로젝트에 있는 데이터 세트가 표시됩니다. state 필드는 데이터 세트를 사용할 준비가 되었는지 여부를 나타냅니다. 데이터 세트가 방금 생성되면 색인 생성이 완료될 때까지 LOADING 상태에 있다가 LOADED 상태로 전환됩니다. 만들기 및 색인 생성 중에 오류가 발생하면 FAILED 상태로 됩니다. 결과에는 원래 만들기 요청의 전체 데이터 세트 정보가 포함됩니다.

데이터 세트 만들기

projects.locations.datasets.create는 프로젝트에 새 데이터 세트를 추가합니다.

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

여기서 create.json에 다음 항목이 포함되어 있습니다.

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

이 요청은 GCS dataSources에서 유래한 dataset_tutorial(이)라는 데이터 세트를 만들고 여기에 JSON 형식의 이벤트 데이터가 포함됩니다. dataNames에 나열된 측정기준만 시스템에서 색인으로 생성되고 사용됩니다.

생성 요청은 API 서버에서 허용되는 경우 성공을 반환합니다. 데이터 세트는 색인 생성이 완료될 때까지 LOADING 상태가 된 다음 LOADED 상태로 되는데 그 후에 데이터 세트에서 쿼리와 업데이트를 수락할 수 있습니다.

데이터 세트 쿼리

projects.locations.datasets.query는 이상 감지 쿼리를 수행합니다.

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

여기서 query.json에 다음 항목이 포함되어 있습니다.

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

쿼리 결과는 다음과 같습니다.

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

스트리밍 업데이트

projects.locations.datasets.appendEvents는 스트리밍 방식으로 이벤트 레코드를 추가합니다.

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

여기서 append.json에는 다음이 포함됩니다(eventTime을(를) 현재 시간과 가까운 타임스탬프로 바꿀 것).

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

스트리밍 업데이트는 거의 실시간으로 색인이 생성되므로 변경사항이 쿼리 결과에 신속하게 반영됩니다. 단일 projects.locations.datasets.appendEvents 요청으로 전송되는 모든 이벤트는 동일한 groupdId을(를) 가져야 합니다.

데이터세트 삭제

projects.locations.datasets.delete는 삭제할 데이터 세트를 표시합니다.

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

요청이 즉시 반환되고 데이터 세트에 대해 추가 쿼리 또는 업데이트가 수락되지 않습니다. 서비스에서 데이터가 완전히 제거되기까지 다소 시간이 걸릴 수 있으며, 그 이후에는 데이터 세트 나열 요청 시 이 데이터 세트가 반환되지 않습니다.

다음 단계

Timeseries Insights API 개념
REST API에 대해 자세히 알아보기

다른 예시는 GDELT 웹사이트에서 'Timeseries Insights API'를 검색하여 확인할 수 있습니다.