> 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 Events](/deployment/ja/to/vision-events.md) — デプロイ済みモデルが観測した内容のタイムスタンプ付きレコード — を、Vision Events ダッシュボードでフィルタリングおよび検索したり、REST API 経由でプログラム的に取得したりして見つける方法を説明します。日付範囲、イベントタイプ、デバイス、ストリーム、ワークフロー、検出クラス、またはフィードバックステータスで結果を絞り込み、本番動作を監査してレポートを作成できます。さらに、 [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) にイベントについて自然言語で質問することもできます。 ## Web アプリ ### イベントのクエリとフィルタリング Vision Events ダッシュボードでフィルターを使って特定のイベントを見つけるか、REST API 経由でプログラム的にクエリします。 #### ダッシュボードでイベントを閲覧する **ユースケースを選択** Vision Events ページからユースケースをクリックすると、そのイベントを表示できます。イベントは新しい順に表示されます。
**イベントをフィルタリングする** イベント一覧の上部にあるフィルターコントロールを使って、結果を次の条件で絞り込みます。 * **日付範囲** — 開始および終了のタイムスタンプ * **イベントタイプ** — quality\_check、inventory\_count、safety\_alert、custom、operator\_feedback * **デバイス** — デバイス ID でフィルタ * **ストリーム** — ストリームまたはカメラ ID でフィルタ * **ワークフロー** — イベントを生成したワークフローでフィルタ * **検出** — 検出されたオブジェクトクラスでフィルタ（任意で信頼度のしきい値を指定可能） * **フィードバックステータス** — correct、incorrect、inconclusive、またはフィードバックなし * **カスタムメタデータ** — 任意のカスタムメタデータのフィールドと値でフィルタ * **警告** — 取り込み警告があったイベントのみを表示 イベント詳細サイドバー内の値（デバイス ID、ストリーム、品質チェック結果、カスタムメタデータ値など）をクリックして、すばやくフィルターとして追加することもできます。 フィルターチップは編集可能です。アクティブなフィルターチップをクリックすると、削除して再追加しなくても、その値や演算子を変更できます。 フィルターが適用されると、 **一致件数の合計** が結果一覧の上部に表示されます。この件数はイベント一覧とは独立して更新されるため、イベントの読み込み中でも、フィルターに一致するイベント数を確認できます。
**イベント詳細を表示** 一覧内の任意のイベントをクリックすると、詳細をすべて表示できます。 * ソース画像と出力画像 * すべてのソースメタデータ（デバイス、ストリーム、ワークフロー） * オブジェクト検出、分類、セグメンテーションとその信頼度スコア * イベントタイプ固有のデータ（例: 成否結果、アイテム数、アラートの重大度） * カスタムメタデータのキーと値のペア **検出結果を描画** イベントに予測データ（オブジェクト検出、インスタンスセグメンテーション、キーポイント）が含まれている場合、画像の上に "Draw Detections" チェックボックスが表示されます。これを有効にすると、元画像の上にバウンディングボックス、セグメンテーションポリゴン、信頼度スコア付きのラベルを重ねて表示できます。 これは、パイプラインが元の入力画像だけを保存し、別の出力画像を保存せずにモデルが検出した内容を可視化したい場合に便利です。 {% hint style="info" %} 個別の出力画像を表示しているときは、その画像にはすでに検出結果が描画されているため、このチェックボックスは非表示になります。 {% endhint %} **自動確定されたイベント** 自動確定としてフラグされたイベントは、動画のアップロード完了前にエッジデバイス上で自動的に閉じられたため、動画は欠落しています。イベントには結果と静止画像は引き続き含まれます。イベントカードにはインジケータが表示され、詳細ビューには確定時刻が表示されます。これは、 [Edge Device Backup](/deployment/ja/to/vision-events/send-events.md#edge-device-backup). ### Agent に質問する 手動でフィルターを作成する代わりに、自然言語でイベントをクエリできます。左サイドバーの [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) をクリックして開き、ユースケースについて質問してください（例: "先週 assembly-line-qa で失敗は何件ありましたか?"、"欠陥率は時間とともにどう変化しましたか?"、"ストリームごとの平均アイテム数はいくつですか?"）。 ユースケース上で "Analyze with AI" をクリックすることもできます。このボタンは Overview と Search タブに表示され、送信準備ができたそのユースケースに関する質問を新しいタブで Agent とともに開きます。Search タブでは、質問には適用中のフィルターも含まれるため、Agent はあなたが見ているのと同じイベントを参照します。 Agent はイベントデータをクエリして応答するため、数値はイベントに実際に含まれている内容を反映します。できること: * 時間範囲、イベントタイプ、または結果に一致するイベントをカウントする。 * 時間とともに合格率・不合格率を追跡し、欠陥率が改善しているか悪化しているかを示す。 * 数値フィールドの合計、平均、最小、最大、または一意な値の数を算出する。 * イベントフィールドやカスタムメタデータごとに合計をグループ化したり、日単位や週単位でバケット化したりする。 質問がワークスペースの [保持期間](/deployment/ja/to/vision-events.md#data-retention)を超える場合、ゼロと答える代わりに、クエリ可能な最も早い日付を Agent が伝えます。日付の境界と時間バケットには UTC を使用します。 イベントについて質問するには、"View Vision Events" の [権限](https://docs.roboflow.com/platform/enterprise-features/role-based-access-control). 必要があります。1回限りの回答ではなく、定期的にメール送信される要約が必要な場合は、 [Summary Reports](/deployment/ja/to/vision-events/summary-reports.md). ## HTTP API ### API 経由でイベントをクエリする クエリエンドポイントはダッシュボードと同じフィルターに加え、カーソルベースのページネーションをサポートしています。パラメータとレスポンスフィールドの完全な一覧は、 [Vision Events API Reference](/deployment/ja/to/vision-events.md#http-api). #### 基本クエリ ```bash curl -X POST "https://api.roboflow.com/vision-events/query" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "useCaseId": "assembly-line-qa", "startTime": "2026-03-01T00:00:00Z", "endTime": "2026-03-31T23:59:59Z", "limit": 25 }' ``` **レスポンス:** ```json { "events": [ { "eventId": "evt-789ghi", "eventType": "quality_check", "timestamp": "2026-03-30T14:30:00.000Z", "deviceId": "factory-cam-01", "streamId": "line-3", "images": [], "eventData": { "result": "fail" }, "customMetadata": { "line_id": "line-3", "shift": "morning", "part_number": "PN-4421" } } ], "nextCursor": "eyJ0cyI6IjIwMjYtMDMtMzAifQ==", "hasMore": true } ``` #### ページネーション 結果はカーソルを使ってページ分割されます。レスポンスに `nextCursor` の値と `hasMore` が `true`の場合は、次のリクエストでそのカーソルを渡して次のページを取得します。 ```bash curl -X POST "https://api.roboflow.com/vision-events/query" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "useCaseId": "assembly-line-qa", "limit": 25, "cursor": "eyJ0cyI6IjIwMjYtMDMtMzAifQ==" }' ``` まで続けます `hasMore` が `false`. #### イベントタイプでフィルタ 単一のイベントタイプをクエリする: ```json { "useCaseId": "assembly-line-qa", "eventType": "quality_check" } ``` または複数のイベントタイプ（最大 20 件）: ```json { "useCaseId": "assembly-line-qa", "eventTypes": ["quality_check", "operator_feedback"] } ``` #### フィードバックステータスでフィルタ 使用 `feedbackStatus` を使って、オペレーターがレビューしたかどうかと評価に基づいてイベントを見つけます: ```json { "useCaseId": "assembly-line-qa", "feedbackStatus": ["incorrect", "none"] } ``` 有効な値: `correct`, `incorrect`, `inconclusive`, `none`。未レビューのイベントを見つけるには `none` を使用します。 #### カスタムメタデータでフィルタ 使用 `customMetadataFilters` を使って、自分のメタデータフィールドでイベントをフィルタします: ```json { "useCaseId": "assembly-line-qa", "customMetadataFilters": [ { "key": "line_id", "operator": "eq", "value": "line-3" }, { "key": "shift", "operator": "eq", "value": "morning" } ] } ``` ### Vision Events をクエリする フィルター、時間範囲、ページネーションを使って vision events をクエリします。このエンドポイントは、イベントタイプ、デバイスコンテキスト、検出クラス、カスタムメタデータ、イベント固有フィールドによるフィルタリングをサポートします。 **必須スコープ:** `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-2afefc06c784ca78eb7ec96a99bee48f8a2daaa5%2Fopenapi.yaml?alt=media) {% endopenapi %} #### リクエスト例 ```bash curl -X POST "https://api.roboflow.com/vision-events/query" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "useCaseId": "a1b3c8e1", "startTime": "2024-01-14T00:00:00Z", "endTime": "2024-01-15T23:59:59Z", "eventTypes": ["quality_check", "safety_alert"], "customMetadataFilters": [ { "field": "temperature", "operator": "gt", "value": 70, "type": "number" } ], "limit": 50 }' ``` #### リクエスト本文のパラメータ **必須フィールド:** * **`useCaseId`** （文字列）: イベントをクエリするユースケース ID。ユースケース ID の見つけ方は [ユースケース](/deployment/ja/to/vision-events/use-cases.md) を参照してください。 **時間範囲フィルター:** * **`startTime`** （文字列、ISO 8601、任意）: 時間範囲の開始。 * **`endTime`** （文字列、ISO 8601、任意）: 時間範囲の終了。 **イベントタイプフィルター:** * **`eventTypes`** （文字列の配列、最大 20、任意）: 1 つ以上のイベントタイプにフィルタします。 **コンテキストフィルター:** 各コンテキストフィルターは `operator` と `value`: * **`deviceId`** （オブジェクト、任意）: デバイスでフィルタします。演算子: `eq`, `neq`. * **`streamId`** （オブジェクト、任意）: ストリームでフィルタします。演算子: `eq`, `neq`. * **`workflowId`** （オブジェクト、任意）: ワークフローでフィルタします。演算子: `eq`, `neq`. * **`externalId`** （オブジェクト、任意）: 外部 ID でフィルタします。演算子: `eq`, `neq`. ```json { "deviceId": { "operator": "eq", "value": "camera-node-5" } } ``` **検出フィルター:** * **`detection`** （オブジェクト、任意）: 検出クラス名でイベントをフィルタします。必要に応じて、各検出の信頼度しきい値を組み合わせることもできます。演算子: `eq`, `neq`, `in`, `not_in`。 `in` と `not_in`では、値として文字列の配列を渡します（最大 50 件）。 * **`confidence`** （オブジェクト、任意）: 検出ごとの信頼度しきい値。 `eq` と `in` クラス演算子と組み合わせた場合のみサポートされます。クラスと信頼度は同じ検出に対して一致している必要があります。 * **`operator`** （文字列）: 次のいずれか `gt`, `gte`, `lt`, `lte`. * **`value`** （数値）: 0〜1 の信頼度しきい値。 ```json { "detection": { "operator": "in", "value": ["defect", "crack"] } } ``` 最小信頼度でクラスをフィルタする: ```json { "detection": { "operator": "eq", "value": "scratch", "confidence": { "operator": "gte", "value": 0.8 } } } ``` {% hint style="info" %} この `detection` フィルターは以前 `detectionClass`と呼ばれていました。旧名は現在受け付けられません。 {% endhint %} **画像および警告フィルター:** * **`imageCount`** （オブジェクト、任意）: イベントに添付された画像数でフィルタします。演算子: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`. * **`hasWarnings`** （ブール、任意）: 取り込み警告があるイベント、またはないイベントにフィルタします。 ```json { "imageCount": { "operator": "gte", "value": 1 } } ``` **カスタムメタデータフィルター:** * **`customMetadataFilters`** （配列、最大 20、任意）: カスタムメタデータフィールドでフィルタします。各フィルターには次が含まれます: * **`field`** （文字列）: メタデータフィールド名。 * **`operator`** （文字列）: 比較演算子。 * **`value`**: 比較対象の値。 * **`type`** （文字列）: 値の型。次のいずれか `string`, `number`、または `boolean`. 型ごとに利用可能な演算子: | 型 | 演算子 | | --------- | ------------------------------------- | | `string` | `eq`, `neq`, `in`, `not_in` | | `number` | `eq`, `neq`, `gt`, `gte`, `lt`, `lte` | | `boolean` | `eq`, `neq` | **イベントフィールドフィルター:** * **`eventFieldFilters`** （配列、最大 20、任意）: イベント固有フィールドでフィルタします。各フィルターには次が含まれます: * **`column`** （文字列）: 次のいずれか `result`, `location`, `item_count`, `item_type`, `alert_type`, `severity`、または `feedback`. * **`operator`** （文字列）: 比較演算子（`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`). * **`value`**: 比較対象の値。 ```json { "eventFieldFilters": [ { "column": "result", "operator": "eq", "value": "fail" } ] } ``` **ページネーション:** * **`cursor`** （文字列、任意）: 次のページを取得するための以前のレスポンスのカーソル。 * **`limit`** （数値、任意、デフォルト 100、最大 1000）: ページごとに返すイベント数。 #### レスポンス例 {% tabs %} {% tab title="200" %} ```json { "events": [ { "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "eventType": "quality_check", "timestamp": "2024-01-15T10:30:00.000Z", "images": [ { "label": "inspection-photo", "objectDetections": [ { "class": "defect", "x": 100, "y": 200, "width": 50, "height": 30, "confidence": 0.95 } ] } ], "eventData": { "result": "fail", "externalId": "batch-001" }, "customMetadata": { "line": "A1", "temperature": 72.5 } } ], "hasMore": false, "lookbackDays": 14 } ``` 次のとき `hasMore` が `true`、 `nextCursor` 値を次のリクエストで使用して、結果の次のページを取得します: ```json { "events": [...], "hasMore": true, "nextCursor": "eyJ0aW1lc3RhbXAiOiIyMDI0LTAxLTE1IiwiZXZlbnRJZCI6InFjLTAwMSJ9", "lookbackDays": 14 } ``` {% endtab %} {% tab title="400" %} ```json { "error": "Invalid query: useCaseId is required" } ``` {% endtab %} {% tab title="403" %} ```json { "error": "Insufficient permissions for this resource." } ``` {% endtab %} {% endtabs %} ## Python SDK フィルター、時間範囲、ページネーションを使って vision events をクエリします。 ### 単一ページのクエリ 使用 `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) すると、これらのツールを使ってイベントに関する質問に答えられます:
ツール説明
vision_events_queryフィルターとページネーションを使用して、本番の vision イベントを検索します。
vision_events_use_cases_listワークスペース内の vision イベントのユースケースを一覧表示します。
vision_events_custom_metadata_schema_getユースケースに対して検出されたカスタムメタデータスキーマを取得します。