> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/ja/to/vision-events/query-events.md).

# イベントを検索

ダッシュボードで Vision Event を検索、フィルタリング、閲覧したり、Agent に自然言語で質問したり、API 経由でクエリしたりできます

## 概要

このページでは、特定の [Vision Events](https://docs.roboflow.com/deployment/ja/to/vision-events.md) （デプロイ済みモデルが認識した内容をタイムスタンプ付きで記録したもの）を、Vision EventsダッシュボードまたはREST APIでフィルタリングや検索して見つける方法を説明します。日付範囲、イベントタイプ、デバイス、ストリーム、ワークフロー、検出クラス、フィードバックの状態で結果を絞り込み、本番環境での動作を監査したり、レポートを作成したりできます。また、 [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) に自然言語でイベントについて質問することもできます。

### 保存済みフィルター

保存済みフィルターはユースケースに属するため、ワークスペース内の全員が開くことができます。相対日付は相対のままです。たとえば、過去7日間のフィルターを保存すると、常に直近7日間が表示されます。Vision Eventsを作成できるユーザーなら誰でも、フィルターを上書き保存できます。名前の変更や削除ができるのは、保存した本人またはVision Eventsを管理できるユーザーだけです。

### 自動確定イベント

自動確定イベントとは、パイプラインが既定の時間（デフォルトでは1時間）内にイベントを確定しなかったため、エッジデバイス上で自動的に終了されたイベントです。パイプラインが添付する予定だった動画がない場合があります。イベントの結果と静止画像は残ります。この機能は、 [エッジデバイスのバックアップ](https://docs.roboflow.com/deployment/ja/to/vision-events/send-events.md#edge-device-backup).

### Agentへの質問

Agentにイベントについて質問するには、「View Vision Events」 [権限](https://docs.roboflow.com/platform/enterprise-features/role-based-access-control)が必要です。質問の対象がワークスペースの [保持期間](https://docs.roboflow.com/deployment/ja/to/vision-events.md#data-retention)より前に及ぶ場合、Agentは該当なしと答えるのではなく、検索可能な最も古い日付を伝えます。日付の境界と時間の区切りにはUTCを使用します。

## Web アプリ

### イベントをフィルタリングする

「Vision Events」を開き、ユースケースをクリックすると、イベントが新しい順に表示されます。

<figure><img src="https://970637113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-95c770d9d0c869e1e12457c562341ea39479ffd2%2Fimage%20(457).png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

フィルターバーを使って、日付、イベントID、イベントタイプ、デバイス、ストリーム、ワークフロー、検出（任意で信頼度しきい値を指定）、フィードバック、カスタムメタデータ、動画数、取り込み時の警告で結果を絞り込めます。開始日または終了日は、「Relative」（例：7日前）または「Absolute」（固定の日時）に設定できます。

テキストフィルター（例：デバイス、ストリーム、カスタムメタデータ）では、「Contains」「Starts With」「Ends With」を使って値の一部に一致させることもできます。これらの照合では大文字と小文字が区別されます。ほとんどのフィルターでは、フィールドが「Is Set」かどうかも確認できます。「is / is not」の切り替えを使うと、反対の条件に一致させられます。

いずれかのフィルターセットに一致するイベントを検索するには、「OR」をクリックしてフィルター行を追加します。少なくとも1行のすべてのフィルターに一致するイベントが表示されます。日付はすべての行に適用されます。

イベント詳細サイドバーの値（例：デバイスIDやカスタムメタデータの値）をクリックすると、その値をフィルターとして追加できます。有効なフィルターチップをクリックすると、値または演算子を変更できます。

一致するイベントの合計数は、リストの読み込み中でも結果の上に表示されます。ユースケースに [イベントの値](https://docs.roboflow.com/deployment/ja/to/vision-events/use-cases.md#event-value)がある場合は、一致したイベントの値の合計も表示されます。

フィルターを再利用するには、フィルターバーの先頭にある「Saved Filters」を開き、「Save Current Filters」をクリックします。「Copy Link」で共有できます。変更できるユーザーについては、 [保存済みフィルター](#saved-filters) を参照してください。

イベントを保存するには、イベントを開いてヘッダーの星をクリックするか、 `S`キーを押します。星を付けたイベントは、自分とユースケースにのみ表示されます。確認するには、「Saved Filters」の横にある「Lists」メニューを開き、「Starred」を選択します。星を付けたイベントは、 [保持期間](https://docs.roboflow.com/deployment/ja/to/vision-events.md#data-retention)を過ぎても表示されます。ユースケースごとに最大1,000件のイベントに星を付けられます。

独自のリストを作成するには、「Lists」を開いてリストを作成し、非公開にするかワークスペースと共有するかを選びます。星の横にあるリストボタンで、イベントをリストに追加します。Vision Eventsを作成できるユーザーなら誰でも共有リストにイベントを追加できますが、名前の変更や削除ができるのは作成者またはVision Eventsを管理できるユーザーだけです。

<figure><img src="https://970637113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-6dd0ace6246d420942f5311802af38fd5988065d%2Fimage%20(458).png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

### イベントの詳細を表示する

イベントをクリックすると、画像、動画クリップ、ソースメタデータ、予測、イベントデータ、カスタムメタデータ、 [値](https://docs.roboflow.com/deployment/ja/to/vision-events/use-cases.md#event-value).

イベントに検出、セグメンテーション、キーポイントが含まれている場合は、「Draw Detections」にチェックを入れると、ソース画像上に描画できます。パイプラインが入力画像のみを保存する場合に便利です。この設定はブラウザーに保存され、すべてのイベントと全画面表示に適用されます。検出結果がすでに表示されている出力画像では、チェックボックスは表示されません。

イベントカードに再生アイコンが表示されている場合、そのイベントには [動画クリップ](https://docs.roboflow.com/deployment/ja/to/vision-events/upload-a-vision-event-video.md)があります。クリップは画像の後にある「Media」ストリップで再生され、処理中のクリップは準備ができると再生されます。検出オーバーレイと全画面表示は画像のみで利用でき、 [トレーニング用にクリップを追加](https://docs.roboflow.com/deployment/ja/to/vision-events/add-images-for-training.md).

取り消し線付きの動画アイコンは、 [自動確定イベント](#auto-finalized-events)を示します。詳細ビューには、イベントが確定された時刻が表示されます。

### ビジュアル検索

ユースケースの「Visual Lookup」タブを使うと、画像の内容を指定してフレームを検索できます。説明（例：夜のフォークリフト）を入力し、「Search」をクリックします。手元にあるフレームに似たフレームを探すには、フレーム上またはイベント詳細ビューで「Find similar frames」をクリックします。結果は類似度順（最も近いものが先）に並び、一致するすべてのフレームが表示されるとは限りません。

検索範囲を絞り込むには、時間帯を選択します。フレームをクリックすると、新しいタブでそのイベントが開きます。イベントに星を付けたり、検索結果から [トレーニング用のフレームを追加](https://docs.roboflow.com/deployment/ja/to/vision-events/add-images-for-training.md) したりすることもできます。このタブを表示するには、Search Workspace Images権限が必要です。新しくアップロードしたフレームは、数分後に検索可能になります。

### エージェントに質問する

左側のサイドバーで「エージェント」をクリックし、次の内容を質問します。 [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) ユースケースについて（例：「assembly-line-qaでは先週、失敗はいくつありましたか？」）。イベントデータを検索して回答します。イベント数のカウント、期間ごとの合格率・不合格率の追跡、数値フィールドの合計・平均・最小値・最大値・ユニーク数の算出、フィールド、カスタムメタデータ、日、週ごとの合計のグループ化、イベント自体の一覧表示（例：「デバイスXのイベントを表示して」）ができます。続きのイベントを表示するには、さらに質問してください。

ユースケースの概要タブまたは検索タブで「AIで分析」をクリックすると、質問が入力された状態で新しいタブにエージェントが開きます。検索タブから開いた場合、質問には現在のフィルターが含まれます。

定期的にメールで配信されるダイジェストについては、 [サマリーレポート](https://docs.roboflow.com/deployment/ja/to/vision-events/summary-reports.md).

## HTTP API

### ビジョンイベントをクエリする

フィルター、時間範囲、ページネーションを指定してビジョンイベントをクエリします。このエンドポイントでは、イベントタイプ、デバイスのコンテキスト、検出クラス、カスタムメタデータ、画像メタデータ、イベント固有のフィールドでフィルタリングできます。

**必須スコープ:** `vision-events:read` または `device:read`

{% openapi src="/files/934e54fa9aa57656316a422a76238b867f081de5" path="/vision-events/query" method="post" %}
[openapi.yaml](https://970637113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% hint style="info" %}
この `detection` フィルターは以前、次の名前でした： `detectionClass`。古い名前は現在使用できません。
{% endhint %}

結果に含まれる各動画には、 `sourceId` および `label`。再生またはダウンロードするには、 [再生URLを取得します](https://docs.roboflow.com/deployment/ja/to/vision-events/upload-a-vision-event-video.md#get-a-playback-url) その `sourceId`.

いずれかのフィルターセットに一致させるには、フィルターを次の形式で送信します。 `filterGroup`。保存済みフィルターを実行するには、そのIDを次のように送信します。 `savedFilterId`そのフィルターで検索タブに表示されるものと同じイベントが取得されます。

### 保存済みフィルター

保存済みフィルターは「検索」タブに表示されるものと同じです。そのため、API 経由で保存したフィルターはウェブアプリにも表示されます。生の API キーはワークスペースとして動作し、フィルターを所有しません。フィルターの名前を変更または削除するには、 `vision-events:manage` スコープが必要です。OAuth トークンはユーザーとして動作するため、そのユーザーは `vision-events:write`を使って自分のフィルターの名前を変更したり、削除したりできます。他のユーザーのフィルターへの変更は、ワークスペースの監査ログに記録されます。

{% openapi src="/files/934e54fa9aa57656316a422a76238b867f081de5" path="/vision-events/use-cases/{useCaseId}/saved-filters" method="get" %}
[openapi.yaml](https://970637113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/934e54fa9aa57656316a422a76238b867f081de5" path="/vision-events/use-cases/{useCaseId}/saved-filters/{savedFilterId}" method="get" %}
[openapi.yaml](https://970637113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/934e54fa9aa57656316a422a76238b867f081de5" path="/vision-events/use-cases/{useCaseId}/saved-filters" method="post" %}
[openapi.yaml](https://970637113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/934e54fa9aa57656316a422a76238b867f081de5" path="/vision-events/use-cases/{useCaseId}/saved-filters/{savedFilterId}" method="patch" %}
[openapi.yaml](https://970637113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/934e54fa9aa57656316a422a76238b867f081de5" path="/vision-events/use-cases/{useCaseId}/saved-filters/{savedFilterId}" method="delete" %}
[openapi.yaml](https://970637113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

## Python SDK

フィルター、時間範囲、ページネーションを指定してビジョンイベントをクエリします。

### 単一ページのクエリ

次を使用します。 `query_vision_events()` 結果の1ページを取得するには：

```python
import roboflow

roboflow.login()

rf = roboflow.Roboflow()
ws = rf.workspace()

page = ws.query_vision_events(
    "a1b3c8e1",                          # ユースケース ID（必須）
    event_type="quality_check",          # 単一のイベントタイプで絞り込む
    start_time="2024-01-14T00:00:00Z",   # ISO 8601 形式の開始時刻
    end_time="2024-01-15T23:59:59Z",     # ISO 8601 形式の終了時刻
    limit=50,                            # 1ページあたりの最大イベント数
)

for evt in page["events"]:
    print(evt["eventId"], evt["eventData"])
```

追加のフィルターをキーワード引数として渡すこともできます。これらは API に直接転送されます。

```python
page = ws.query_vision_events(
    "a1b3c8e1",
    event_types=["quality_check", "safety_alert"],
    deviceId={"operator": "eq", "value": "camera-node-5"},
    customMetadataFilters=[
        {"field": "temperature", "operator": "gt", "value": 70, "type": "number"}
    ],
    eventFieldFilters=[
        {"column": "result", "operator": "eq", "value": "fail"}
    ],
)
```

手動でページネーションを行う場合は、 `cursor` パラメーターに、前回のレスポンスの `nextCursor` の値を指定します。

```python
all_events = []
page = ws.query_vision_events("a1b3c8e1", limit=100)
all_events.extend(page.get("events", []))

while page.get("hasMore"):
    page = ws.query_vision_events("a1b3c8e1", cursor=page["nextCursor"], limit=100)
    all_events.extend(page.get("events", []))
```

### すべての結果をページネーションで取得する

すべての一致するイベントを自動的にページネーションで取得するには、 `query_all_vision_events()` を使用します。この関数はイベントを1ページずつ返します。

```python
all_events = []

for page in ws.query_all_vision_events(
    "a1b3c8e1",
    event_type="quality_check",
    start_time="2024-01-14T00:00:00Z",
    end_time="2024-01-15T23:59:59Z",
):
    all_events.extend(page)

print(f"Found {len(all_events)} events")
```

利用可能なフィルター、演算子、レスポンス形式の詳細については、 [REST API リファレンス](#http-api).

## MCPサーバー

AI エージェントを [MCP サーバー](https://docs.roboflow.com/agents/mcp-server) に接続すると、次のツールを使ってイベントに関する質問に回答できます。

<table data-search="false"><thead><tr><th width="290">ツール</th><th>説明</th></tr></thead><tbody><tr><td><code>vision_events_query</code></td><td>フィルターとページネーションを使用して、本番環境のビジョンイベントをクエリします。</td></tr><tr><td><code>vision_events_use_cases_list</code></td><td>ワークスペース内のビジョンイベントのユースケースを一覧表示します。</td></tr><tr><td><code>vision_events_custom_metadata_schema_get</code></td><td>ユースケースで検出されたカスタムメタデータスキーマを取得します。</td></tr></tbody></table>
