> 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 を通じたプログラム操作で取得する方法を説明します。日付範囲、イベント種別、デバイス、ストリーム、ワークフロー、検出クラス、またはフィードバックステータスで結果を絞り込み、本番動作を監査してレポートを作成します。

## Web アプリ

### イベントのクエリとフィルタリング

Vision Events ダッシュボードのフィルタを使うか、REST API 経由でプログラム的にクエリして、特定のイベントを見つけます。

#### ダッシュボードでイベントを閲覧する

**ユースケースを選択する**

Vision Events ページでユースケースをクリックすると、そのイベントを表示できます。イベントは新しい順に表示されます。

<figure><img src="/files/e3cffcc60c41e9d9a0912b6740a8167651691f71" alt="" width="375"><figcaption></figcaption></figure>

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

イベント一覧の上部にあるフィルタコントロールを使って、次の条件で結果を絞り込めます:

* **日付範囲** - 開始および終了タイムスタンプ
* **イベント種別** - quality\_check、inventory\_count、safety\_alert、custom、operator\_feedback
* **デバイス** - デバイス ID で絞り込む
* **ストリーム** - ストリームまたはカメラ ID で絞り込む
* **ワークフロー** - イベントを生成したワークフローで絞り込む
* **検出** - 検出されたオブジェクトクラスで絞り込み、必要に応じて信頼度しきい値を指定
* **フィードバックステータス** - correct、incorrect、inconclusive、またはフィードバックなし
* **カスタムメタデータ** - 任意のカスタムメタデータフィールドと値で絞り込む
* **警告** - 取込警告があったイベントのみを表示

イベント詳細サイドバーの値（デバイス ID、ストリーム、品質チェック結果、カスタムメタデータ値など）をクリックすると、それらをフィルタとしてすばやく追加することもできます。

フィルタチップは編集可能です。アクティブなフィルタチップをクリックすると、削除して再追加しなくても値や演算子を変更できます。

フィルタを適用すると、 **一致したイベントの総数** が結果一覧の上部に表示されます。この件数はイベント一覧とは独立して更新されるため、イベントの読み込み中でも、どれだけのイベントがフィルタに一致しているか確認できます。

<figure><img src="/files/d5795b647c566bf7062ce5a9b2709458afbb9c31" alt="" width="375"><figcaption></figcaption></figure>

**イベント詳細を表示する**

一覧の任意のイベントをクリックすると、その全詳細を表示できます:

* ソース画像と出力画像
* すべてのソースメタデータ（デバイス、ストリーム、ワークフロー）
* オブジェクト検出、分類、セグメンテーションとその信頼度スコア
* イベント種別固有のデータ（例: 合格/不合格結果、アイテム数、アラートの重大度）
* カスタムメタデータのキーと値のペア

**検出を描画**

イベントに予測データ（オブジェクト検出、インスタンスセグメンテーション、またはキーポイント）が含まれる場合、画像の上に「検出を描画」チェックボックスが表示されます。これを有効にすると、ソース画像の上にバウンディングボックス、セグメンテーションポリゴン、信頼度スコア付きラベルを重ねて表示できます。

パイプラインが元の入力画像だけを保存し、別の出力画像を保存せずにモデルが検出した内容を可視化したい場合に便利です。

{% hint style="info" %}
別の出力画像を表示している場合は、すでに検出結果が描画されているため、チェックボックスは非表示です。
{% endhint %}

**自動確定イベント**

自動確定としてフラグ付けされたイベントは、動画のアップロード完了前にエッジデバイス上で自動的に閉じられたため、動画はありません。イベントには結果と静止画が残ります。イベントカードにはインジケーターが表示され、詳細ビューには確定時刻が表示されます。これは、次を通じて同期されたイベントにのみ適用されます [エッジデバイスのバックアップ](/deployment/ja/to/vision-events/send-events.md#edge-device-backup).

## HTTP API

### API 経由でイベントをクエリする

クエリエンドポイントは、ダッシュボードと同じフィルタに加えて、カーソルベースのページネーションをサポートします。パラメータとレスポンスフィールドの全一覧については、 [Vision Events API リファレンス](/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: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-dfdc1702ad3d1a62ad0a661e9609f6bbe2fc8d4c%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`** (string): イベントをクエリする対象のユースケース ID。参照してください [ユースケース](/deployment/ja/to/vision-events/use-cases.md) でユースケース ID を見つける方法を確認してください。

**時間範囲フィルタ:**

* **`startTime`** (string, ISO 8601、オプション): 時間範囲の開始。
* **`endTime`** (string, ISO 8601、オプション): 時間範囲の終了。

**イベント種別フィルタ:**

* **`eventTypes`** (string の配列、最大20件、オプション): 1つ以上のイベント種別に絞り込みます。

**コンテキストフィルタ:**

各コンテキストフィルタは次を含むオブジェクトです `operator` および `value`:

* **`deviceId`** (object、オプション): デバイスでフィルタします。演算子: `eq`, `neq`.
* **`streamId`** (object、オプション): ストリームでフィルタします。演算子: `eq`, `neq`.
* **`workflowId`** (object、オプション): ワークフローでフィルタします。演算子: `eq`, `neq`.
* **`externalId`** (object、オプション): 外部 ID でフィルタします。演算子: `eq`, `neq`.

```json
{
  "deviceId": { "operator": "eq", "value": "camera-node-5" }
}
```

**検出フィルタ:**

* **`detection`** (object、オプション): 検出クラス名でイベントをフィルタし、必要に応じて各検出の信頼度しきい値を組み合わせられます。演算子: `eq`, `neq`, `in`, `not_in`。 `in` および `not_in`を使う場合は、値として文字列の配列を渡します（最大50件）。
  * **`confidence`** (object、オプション): 各検出の信頼度しきい値。 `eq` および `in` class 演算子でのみサポートされます。クラスと信頼度は同じ検出上で一致する必要があります。
    * **`operator`** (文字列): 次のいずれか `gt`, `gte`, `lt`, `lte`.
    * **`value`** (number): 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`** (object、オプション): イベントに添付された画像の数でフィルタします。演算子: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`.
* **`hasWarnings`** (boolean、オプション): 取込警告があるイベント、またはないイベントに絞り込みます。

```json
{
  "imageCount": { "operator": "gte", "value": 1 }
}
```

**カスタムメタデータフィルタ:**

* **`customMetadataFilters`** (array、最大20件、オプション): カスタムメタデータフィールドでフィルタします。各フィルタには次が含まれます:
  * **`field`** (string): メタデータフィールド名。
  * **`operator`** (string): 比較演算子。
  * **`value`**: 比較対象の値。
  * **`type`** (string): 値の型。次のいずれか: `文字列`, `数値`、または `boolean`.

型ごとに利用可能な演算子:

| 型         | 演算子                                   |
| --------- | ------------------------------------- |
| `文字列`     | `eq`, `neq`, `in`, `not_in`           |
| `数値`      | `eq`, `neq`, `gt`, `gte`, `lt`, `lte` |
| `boolean` | `eq`, `neq`                           |

**イベントフィールドフィルタ:**

* **`eventFieldFilters`** (array、最大20件、オプション): イベント固有フィールドでフィルタします。各フィルタには次が含まれます:
  * **`column`** (文字列): 次のいずれか `result`, `location`, `item_count`, `item_type`, `alert_type`, `severity`、または `feedback`.
  * **`operator`** (string): 比較演算子（`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`).
  * **`value`**: 比較対象の値。

```json
{
  "eventFieldFilters": [
    { "column": "result", "operator": "eq", "value": "fail" }
  ]
}
```

**ページネーション:**

* **`カーソル`** (string、オプション): 次のページを取得するための、前のレスポンスのカーソル。
* **`limit`** (number、オプション、デフォルト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": "無効なクエリ: useCaseId は必須です"
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "error": "このリソースに対する権限が不十分です。"
}
```

{% endtab %}
{% endtabs %}

## Python SDK

フィルタ、時間範囲、ページネーションを使って vision events をクエリします。

### 単一ページクエリ

次を使用します `query_vision_events()` 単一ページの結果を取得します:

```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,                            # ページごとの最大イベント数
)

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"}
    ],
)
```

手動ページネーションでは、 `カーソル` パラメータと `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回に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"{len(all_events)} 件のイベントが見つかりました")
```

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