Timeseries Insights API

解決する課題

• 多数のサービス・地域・製品など次元の組み合わせが膨大で、どの組み合わせが異常かを人手で追えない
• アクセスログ・取引・センサーなどのイベントデータをリアルタイムに監視し、急増・急減を即座に検知したい
• 単一の指標だけでなく、多次元のスライスごとに異常を切り分けて原因の当たりを付けたい
• 時系列の予測値と実測値の乖離を自動で評価し、しきい値を手で決めずに異常を見つけたい
• 既存のメトリクス監視（しきい値アラート）では高カーディナリティなデータに対応しきれない

主要概念と用語

• データセット (DataSet): 異常検知・予測の対象となるイベントの集合。取り込んだイベント全体を1つの単位として管理する
• イベント (Event): 1件の出来事を表すレコード。発生時刻（タイムスタンプ）と、複数の次元（ディメンション）を持つ
• 次元 (Dimension): イベントの属性。文字列などのカテゴリ次元（地域・製品IDなど）と、数値を持つ**測定次元（数値ディメンション）**がある
• スライス (Slice): カテゴリ次元の値を固定して切り出した、イベントの部分集合。たとえば「地域=東京 かつ 製品=A」のような組み合わせを指す
• ピン留め次元 (pinnedDimensions): スライスを特定するために値を固定する次元の指定。固定したスライスについて時系列を取得・評価する
• 検知時刻 (detectionTime): 「この時点で異常か」を判定する対象の時刻。これより前を学習、付近を評価に使う
• 異常スコア (anomalyScore): 予測値と実測値の乖離度合いを表す指標。値が大きいほど異常度が高く、リスクレベル（低・中・高・非常に高い）に対応づく
• データセットへのクエリ (queryDataSet): データセット全体を走査し、異常なスライスを探し出す主操作。内部で予測も行う
• スライス評価 (evaluateSlice): 値を固定した特定のスライスについて、予測と異常判定の詳細を返す操作

仕様・制限・クォータ

• イベントはタイムスタンプ＋複数次元で構成し、Cloud Storage 上のファイルから一括取り込み、または Pub/Sub でストリーミング追加できる
• 大量の履歴データを最初に読み込むコールドスタート取り込みの後、新しいイベントをリアルタイムに追記していく運用に向く
• 異常検知クエリは、検知時刻より前の期間を学習に、検知時刻付近を評価に用い、予測と実測の乖離からスコアを算出する
• 異常スコアにはリスクレベルが対応づく。一般にスコアが大きいほど高リスクとして扱われ、しきい値で採否を切り分ける
• 1プロジェクトあたりのデータセット数、扱える次元数、イベント数などには上限がある。具体的な上限値・クォータは変動するため公式ドキュメントで確認する
• 利用できるリージョンや料金体系もサービス更新で変わるため、最新は公式情報を参照する

内部の仕組み

Timeseries Insights API は、取り込んだイベント群をカテゴリ次元の組み合わせ（スライス）に展開し、各スライスを時系列に集計します。異常検知クエリを受けると、API は検知時刻より前のデータからスライスごとの予測モデルを内部で構築し、検知時刻付近の予測値と実測値の乖離を評価します。乖離が大きいスライスを異常として、異常スコアとともに返します。

このとき、すべてのスライスを総当たりで評価するのではなく、効率的な探索とインデックスにより、数兆規模のイベントでも実用的な応答時間で異常な組み合わせを見つけられる設計になっています。これにより「どの次元の、どの値の組み合わせで異常が起きているか」を、しきい値を手で設定することなく自動で浮かび上がらせます。

設計パターン / ベストプラクティス

• **取り込み = Cloud Storage（履歴）＋ Pub/Sub（リアルタイム）**の二段構えにし、コールドスタートで過去分を読み込んでから追記運用へ移す
• 次元設計を慎重に行う。カテゴリ次元を増やしすぎるとスライスが爆発するため、監視したい切り口に絞る
• 検知時刻と学習期間を業務サイクルに合わせる。曜日・季節性のある指標は十分な学習期間を確保する
• まず queryDataSet で異常なスライスを発見し、気になる組み合わせを evaluateSlice で深掘りする流れにする
• 異常スコアのしきい値でアラートをルーティングし、高リスクのみ通知、中リスクはダッシュボード表示などに振り分ける
• 検知結果を Pub/Sub → Cloud Functions などに流し、後続の通知・自動対応につなげる

運用・監視

• Cloud Monitoring / Cloud Logging で API のリクエスト数・エラー率・レイテンシを監視する
• 取り込みの遅延や欠損は異常検知の精度に直結するため、イベントの取り込みステータスを継続的に確認する
• 異常スコアの分布や検知件数の推移を見て、しきい値が緩すぎ・厳しすぎないかを定期的に見直す
• データの傾向が変わったとき（新製品追加・季節変動など）は、学習期間や次元設計を再評価する

コスト

• 課金は基本的に処理するイベント量やクエリに応じる。次元の組み合わせを増やすほどスライス数が増え、処理コストも増えやすい
• 監視に不要な次元を含めず、必要な切り口だけを取り込むことでコストとノイズの両方を抑えられる
• リアルタイム追記と一括取り込みを使い分け、過剰なクエリ頻度を避けると無駄が減る
• 具体的な単価は変動するため、見積もりは公式の料金ページで確認する

セキュリティ

• サービスアカウント + IAM で最小権限を付与し、認証情報のハードコードを避ける（AWS の IAM ロール相当）
• 取り込み元の Cloud Storage バケットや Pub/Sub トピックへのアクセスを限定し、データ経路を絞る
• 保存データは Google 管理鍵で既定暗号化される。要件に応じて鍵管理ポリシーを確認する
• 機密性の高いイベントを扱う場合は VPC Service Controls などでデータ境界を設けることを検討する

関連サービス・比較

しきい値ベースの監視に使う Cloud Monitoring と比べると、Timeseries Insights API は多次元・高カーディナリティのイベントに対する自動異常検知に強みがあります。汎用的な機械学習で時系列予測モデルを自作したい場合は Vertex AI が選択肢になります。

ハンズオン / CLI例

Timeseries Insights API は主に REST/クライアントライブラリで利用します。API の有効化は gcloud で行い、データセット作成や異常検知クエリは REST で実行するのが基本です。

# 1) Timeseries Insights API を有効化
gcloud services enable timeseriesinsights.googleapis.com

# 2) アクセストークンを取得（後続の curl で使用）
TOKEN=$(gcloud auth print-access-token)
PROJECT=$(gcloud config get-value project)

# 3) データセット一覧を確認（REST 経由）
curl -X GET \
  -H "Authorization: Bearer ${TOKEN}" \
  "https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT}/locations/-/datasets"

# 4) 異常検知クエリの最小例（検知時刻と対象次元を指定して送る）
#    DATASET_NAME は作成済みデータセット名に置き換える
curl -X POST \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  "https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT}/locations/-/datasets/DATASET_NAME:query" \
  -d '{
        "detectionTime": "2026-06-28T00:00:00Z",
        "numReturnedSlices": 10,
        "forecastParams": {"horizonDuration": "3600s"}
      }'