> 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/use-cases.md).

# Use Case

Use Case を使って目的ごとに Vision Event をグループ化します。

## 概要

ユースケースは、共通の目的とカスタムメタデータ構造を持つ [Vision Events](https://docs.roboflow.com/deployment/ja/to/vision-events.md) をグループ化するものです。各イベントは必ず1つのユースケースに属します。このようにイベントを整理すると、同じフィールドを送信するカメラ、デバイス、拠点間でデータを簡単にフィルタリングして比較できます。

カスタムメタデータのフィールドが同じイベントは、拠点、カメラ、デバイスが異なっていても、同じユースケースにまとめます。例えば、「欠陥検出」ユースケースでは、複数の工場からイベントを受信し、そのすべてに `line_id`, `shift`、および `part_number`が含まれる場合があります。メタデータ構造が異なる場合は、別々のユースケースを作成します。

* 組立ラインの品質保証： `line_id`, `shift`, `part_number`
* 倉庫在庫： `aisle`, `shelf`, `item_type`
* 建設現場の安全： `zone`, `alert_type`, `contractor`

イベントが到着すると、Roboflowは受信したフィールドと値の型からカスタムメタデータスキーマを推定します。スキーマを確認するには、 [カスタムメタデータスキーマの取得](https://docs.roboflow.com/deployment/ja/to/vision-events/get-custom-metadata-schema.md).

を呼び出します。 [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) は、Vision Eventsを含むワークフローを構築するときにユースケースを作成します。適合する既存のユースケースがあれば、それを再利用します。ユースケースの作成を依頼することもできます。

ユースケースをアーカイブすると、デフォルトのビューから非表示になります。イベントは保持され、ユースケースのアーカイブを解除できます。アーカイブ済みのユースケースに送信されたイベントも保存されますが、イベントごとに警告が返されます。

### イベントの価値

イベントに金額を設定すると、ユースケースが生み出す価値を追跡できます（例：検出された欠陥1件あたりのコスト）。ユースケースにデフォルトの値と通貨を設定します。独自の値を指定せずに送信された新しいイベントにはデフォルト値が適用されます。送信済みのイベントの値は変わりません。

イベントは、 `valueBaseUnits` で独自の値を送信することもできます（ [Vision Eventの作成](https://docs.roboflow.com/deployment/ja/to/vision-events/create-a-vision-event.md#http-api)を参照）。値の通貨は常にユースケースの通貨です。値の合計は約5分ごとに更新されます。

### チェックリスト

チェックリストは、ユニットがステーションで通過しなければならない手順を追跡します（例：基板上の4本のネジの確認）。各チェックリストには名前と項目のリストがあります。ユースケースには最大20個のチェックリストを設定でき、各チェックリストには最大50個の項目を設定できます。Roboflowは `quality_check` イベントからチェックリストのステータスを読み取ります。ステータスを別途保存することはありません。

各ユニットには1つのウィンドウが割り当てられます。次の `customMetadata` キーを、そのユニットのすべての `quality_check` イベントで送信してください。

* `checklistId`：チェックリストのID。
* `checklistWindowId`：ユニットごとに1つのID（シリアル番号など）。そのユニットのすべてのイベントで同じIDを使用します。
* `checklistRole`: `window_open`, `item`、または `window_close`.
* `checklistItemId`：結果の対象となる項目です。これは `item` イベントでのみ送信してください。

item `イベントでは、` eventData.result `を` に設定します。 `pass` または `fail`。各イベントに固有の `eventId`を指定してください。同じ `eventId`, `timestamp`と `useCaseId` を持つイベントは、先に送信されたイベントを置き換えます。

「Require Order」（APIでは`ordered` ）をオンにすると、項目を順番にパスさせることができます。この場合、パスとしてカウントされるのは、それより前のすべての項目がパス済みの場合のみです。また、失敗すると、その項目とそれ以降のすべての項目がクリアされます。オフの場合、項目は順不同でパスでき、後から失敗してもパス済みの項目はクリアされません。

## Web App

ワークスペースの左サイドバーで「Vision Events」を開き、「+ Create Use Case」をクリックします。

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

Use Cases テーブルには、各ユースケースのイベント数、最終イベントの時刻、イベントタイプ、累計値が表示されます。ユースケースの概要にある「Value Created」タイルには、そのユースケースの値が表示されます。

デフォルトの [イベント値](#event-value)を設定するには、ユースケースのメニューを開き、「Update Settings」をクリックして、「Default Event Value」と「Currency」を入力します。

チェックリストを [追加するには](#checklists)、ユースケースのメニューを開いて「Edit Checklists」をクリックし、次に「Add Checklist」をクリックします。「Save Checklists」をクリックして変更を保存します。各ユニットの進捗を確認するには、ユースケースを開いて「Checklists」タブをクリックします。Connect Guide には、チェックリスト ID を使ったチェックリストイベントのサンプルが掲載されています。

ダッシュボードからユースケースをアーカイブできます。アーカイブ済みのユースケースを確認するには、テーブルの下部にある「View archived use cases」をクリックします。

<figure><img src="https://970637113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-a19e941a3d1c11eebe09fc1426edc618aef53913%2FDashboard%20view%20for%20solution%20nine%20status.png?alt=media" alt=""><figcaption></figcaption></figure>

## HTTP API

制限のないワークスペース API キーには、デフォルトで `vision-events:manage` スコープが設定されています。

### ユースケースを作成する

ワークスペースに新しいユースケースを作成します。ユースケースを使うと、デプロイ環境（例：「製造ライン 1」、「倉庫の在庫」）ごとにビジョンイベントを整理できます。

**必須スコープ：** `vision-events:manage`

{% openapi src="/files/934e54fa9aa57656316a422a76238b867f081de5" path="/vision-events/use-cases" 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 %}

#### 注意事項

* 新しいユースケースは、デフォルトでステータスが `active` に設定されます。
* ユースケースを作成した後、その `id` を `useCaseId` として参照できます [ビジョンイベントの作成](https://docs.roboflow.com/deployment/ja/to/vision-events/create-a-vision-event.md#http-api).

### ユースケースを更新する

既存のユースケースの名前、ステータス、デフォルトイベント値、またはチェックリストを更新します。 `checklists` を送信すると、ユースケースのすべてのチェックリストが置き換えられます。

**必須スコープ：** `vision-events:manage`

{% openapi src="/files/934e54fa9aa57656316a422a76238b867f081de5" path="/vision-events/use-cases/{useCaseId}" method="put" %}
[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 %}

### ユースケースの一覧表示

ワークスペース内のユースケースを一覧表示します。ユースケースの作成と管理方法については、 [ユースケースのドキュメント](https://docs.roboflow.com/deployment/ja/to/vision-events/use-cases.md).

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

{% openapi src="/files/934e54fa9aa57656316a422a76238b867f081de5" path="/vision-events/use-cases" 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 %}

### ユースケースをアーカイブする

ステータスを `inactive`に設定して、ユースケースをアーカイブします。アーカイブされたユースケースは、デフォルトでは一覧に表示されません。アーカイブ済みのユースケースに送信されたイベントは引き続き保存されますが、 `entity_not_found` 警告が返されます。

**必須スコープ：** `vision-events:manage`

{% openapi src="/files/934e54fa9aa57656316a422a76238b867f081de5" path="/vision-events/use-cases/{useCaseId}/archive" 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 %}

#### 注意事項

* アーカイブは論理削除です。ユースケースとそのイベントは保持されますが、アクティブな一覧には表示されません。
* アーカイブ済みのユースケースを表示するには、 [ユースケースの一覧表示](#http-api) エンドポイントで `status=inactive`.
* アーカイブ済みのユースケースは、 [ユースケースのアーカイブを解除する](#http-api) エンドポイントを使って復元できます。

### ユースケースのアーカイブを解除する

ステータスを `active`.

**必須スコープ：** `vision-events:manage`

{% openapi src="/files/934e54fa9aa57656316a422a76238b867f081de5" path="/vision-events/use-cases/{useCaseId}/unarchive" 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 %}

#### 注意事項

* に戻して、以前にアーカイブしたユースケースを復元します。 `inactive` ステータスのユースケースのみ、アーカイブを解除できます。
* アーカイブを解除すると、ユースケースは再びアクティブな一覧に表示され、新しいイベントでは警告が返されなくなります。

## Python SDK

各ビジョンイベントはユースケースに関連付けられます。Python SDK には、ユースケースの作成、一覧表示、名前変更、アーカイブ、アーカイブ解除を行うメソッドが用意されています。

### ユースケースの一覧表示

```python
import roboflow

roboflow.login()

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

result = ws.list_vision_event_use_cases()

for uc in result["useCases"]:
    print(uc["id"], uc["name"], uc.get("status"))
```

ステータスで絞り込めます。

```python
# アクティブなユースケースのみを一覧表示
result = ws.list_vision_event_use_cases(status="active")
```

### ユースケースを作成する

```python
result = ws.create_vision_event_use_case("manufacturing-qa")
use_case_id = result["id"]
print(f"Created use case: {use_case_id}")
```

### ユースケースの名前を変更する

```python
ws.rename_vision_event_use_case("a1b3c8e1", "updated-name")
```

### ユースケースをアーカイブする

```python
ws.archive_vision_event_use_case("a1b3c8e1")
```

### ユースケースのアーカイブを解除する

```python
ws.unarchive_vision_event_use_case("a1b3c8e1")
```

ユースケース管理の詳細については、 [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_use_cases_list</code></td><td>ワークスペース内のビジョンイベントのユースケースを一覧表示します。</td></tr><tr><td><code>vision_events_use_case_create</code></td><td>新しいビジョンイベントのユースケースを作成します。</td></tr><tr><td><code>vision_events_use_case_rename</code></td><td>既存のユースケースの名前を変更します。</td></tr><tr><td><code>vision_events_use_case_archive</code></td><td>ユースケースをアーカイブします。</td></tr><tr><td><code>vision_events_use_case_unarchive</code></td><td>以前にアーカイブしたユースケースを復元します。</td></tr></tbody></table>
