> 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 Cases

## 概要

ユースケースはグループ化します [Vision Events](/deployment/ja/to/vision-events.md) 共通の目的とカスタムメタデータ構造を共有し、すべてのイベントはちょうど1つのユースケースに属します。このようにイベントを整理すると、同じフィールドを報告するカメラ、デバイス、場所間でデータを簡単にフィルタリングして比較できます。このページでは、1つのユースケースを使う場合と複数を使う場合の違い、およびそれらの作成・管理方法を説明します。

## Web アプリ

### ユースケース

ユースケースは、共通の目的とカスタムメタデータ構造を共有するVisionイベントをグループ化します。各イベントは必ずちょうど1つのユースケースに属します。同じユースケース内のイベントは通常同じメタデータフィールドを共有するため、異なるソース間のデータを簡単にフィルタリングして比較できます。

#### 1つのユースケースと複数のユースケースを使い分けるタイミング

**イベントを同じユースケースに入れる** 異なる場所、カメラ、デバイスから来ていても、類似したカスタムメタデータフィールドを共有している場合。たとえば、「不良検出」ユースケースは複数の工場からイベントを受け取ることがありますが、すべてのイベントには `line_id`, `shift`、および `part_number`.

**別々のユースケースを作成する** メタデータ構造が根本的に異なる場合。たとえば：

* **組立ラインQA** - を追跡 `line_id`, `shift`, `part_number`
* **倉庫在庫** - を追跡 `通路`, `棚`, `item_type`
* **建設現場の安全** - を追跡 `zone`, `alert_type`, `請負業者`

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

**エージェント経由**

この [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) Visionイベントを使ったワークフローを構築すると、ユースケースを自動的に作成します。既存のユースケースが適合する場合はそれを選び、そうでなければ説明されたユースケースに基づいて新しいものを作成します。エージェントに直接、新しいユースケースを設定するよう依頼することもできます。

**ダッシュボードで**

1. 移動する **Vision Events** ワークスペースの左サイドバーで
2. クリックする **+ ユースケースを作成**
3. ユースケースの名前を入力する

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

REST API経由でもユースケースを作成できます。詳細は [プログラムでユースケースを管理する](#manage-use-cases-programmatically).

#### ユースケースを表示

**ダッシュボードで**

Visionイベントページには、すべてのユースケースの表が表示され、次の項目が示されます：

* ユースケース名
* イベント総数
* 最新イベントのタイムスタンプ
* 使用中のイベントタイプ

**API経由**

ワークスペース内のすべてのユースケースを取得します：

```bash
curl -X GET "https://api.roboflow.com/vision-events/use-cases" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

次を参照してください [Vision Events API リファレンス](/deployment/ja/to/vision-events.md#http-api) 完全なレスポンス形式について。

#### プログラムでユースケースを管理する

ダッシュボードに加えて、REST API経由でユースケースの作成、名前変更、アーカイブ、アーカイブ解除を行えます。これらのエンドポイントには、 `vision-events:manage` スコープを持つAPIキーが必要です（制限なしのワークスペースAPIキーはデフォルトでアクセス権があります）。

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

```bash
curl -X POST "https://api.roboflow.com/vision-events/use-cases" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "name": "assembly-line-qa" }'
```

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

```bash
curl -X PUT "https://api.roboflow.com/vision-events/use-cases/USE_CASE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "name": "assembly-line-qa-v2" }'
```

**ユースケースをアーカイブまたはアーカイブ解除する**

```bash
curl -X POST "https://api.roboflow.com/vision-events/use-cases/USE_CASE_ID/archive" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST "https://api.roboflow.com/vision-events/use-cases/USE_CASE_ID/unarchive" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

ユースケースは、不要になったらダッシュボードからアーカイブできます。アーカイブされたユースケースとそのイベントは引き続きアクセスできますが、既定の表示では非表示になります。 **アーカイブ済みユースケースを表示** ユースケース表の下部にあるをクリックすると表示できます。\ <br>

<figure><img src="/files/926e4c10f2fd01ee81c2a00d02f1fe11f4a690e9" alt=""><figcaption></figcaption></figure>

#### カスタムメタデータスキーマ

イベントがユースケースに送信されると、システムは観測されたフィールドと値の型に基づいてメタデータスキーマを推定します。ユースケースの推定スキーマを取得して、どのキーと値の型が使われているかを把握できます：

```bash
curl -X GET "https://api.roboflow.com/vision-events/custom-metadata-schema/assembly-line-qa" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**応答例：**

```json
{
  "useCaseId": "assembly-line-qa",
  "fields": {
    "line_id": { "types": ["string"] },
    "shift": { "types": ["string"] },
    "temperature": { "types": ["number"] },
    "is_priority": { "types": ["boolean"] }
  }
}
```

次を参照してください [Vision Events API リファレンス](/deployment/ja/to/vision-events.md#http-api) 詳細については。

## HTTP API

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

ワークスペースに新しいユースケースを作成します。ユースケースは、展開コンテキストごとにVisionイベントを整理するのに役立ちます（例：「Manufacturing Line 1」「Warehouse Inventory」）。

**必要なスコープ:** `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-2afefc06c784ca78eb7ec96a99bee48f8a2daaa5%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### リクエスト本文のパラメータ

* **`name`** (string, required): ユースケースの名前。1〜256文字である必要があります。名前の前後の空白は削除され、ワークスペース内で一意でなければなりません。

#### リクエスト例

```bash
curl -X POST "https://api.roboflow.com/vision-events/use-cases" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Manufacturing Line 1"
  }'
```

#### レスポンス例

{% tabs %}
{% tab title="201" %}

```json
{
  "id": "a1b3c8e1",
  "name": "Manufacturing Line 1"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "この名前のソリューションは既に存在します"
}
```

{% endtab %}

{% tab title="403" %}

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

{% endtab %}
{% endtabs %}

#### 注記

* 新しいユースケースは既定で `有効` ステータスで作成されます。
* ユースケース名はワークスペース内で一意である必要があります。既存のものと同じ名前でユースケースを作成しようとすると、 `400` エラーが返されます。
* ユースケースを作成した後は、その `id` を `useCaseId` として [Visionイベントを作成する際に](/deployment/ja/to/vision-events/create-a-vision-event.md#http-api).

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

既存のユースケースの名前またはステータスを更新します。

**必要なスコープ:** `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-2afefc06c784ca78eb7ec96a99bee48f8a2daaa5%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### パスパラメータ

* **`useCaseId`** (string, required): 更新するユースケースのID。

#### リクエスト本文のパラメータ

少なくとも次のいずれか1つのフィールドを指定する必要があります：

* **`name`** (string, optional): ユースケースの新しい名前。1〜256文字である必要があります。ワークスペース内で一意でなければなりません。
* **`status`** (string, optional): 新しいステータス。次のいずれか： `有効` または `inactive`.

#### リクエスト例

```bash
curl -X PUT "https://api.roboflow.com/vision-events/use-cases/a1b3c8e1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Manufacturing Line 2"
  }'
```

#### レスポンス例

{% tabs %}
{% tab title="200" %}

```json
{
  "id": "a1b3c8e1",
  "name": "Manufacturing Line 2"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "この名前のソリューションは既に存在します"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "error": "ソリューションが見つかりません"
}
```

{% endtab %}

{% tab title="403" %}

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

{% endtab %}
{% endtabs %}

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

ワークスペース内でVisionイベントを記録したすべてのユースケースを一覧表示します。ユースケースの作成と管理の詳細は、 [ユースケースのドキュメント](/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-2afefc06c784ca78eb7ec96a99bee48f8a2daaa5%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### クエリパラメータ

* **`status`** (string, optional): ユースケースのステータスで絞り込みます。次のいずれか `有効` または `inactive`。既定値は `有効`.

#### リクエスト例

```bash
curl "https://api.roboflow.com/vision-events/use-cases" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### レスポンス例

{% tabs %}
{% tab title="200" %}

```json
{
  "useCases": [
    {
      "id": "a1b3c8e1",
      "name": "Manufacturing Line 1",
      "status": "active",
      "workspaceId": "my-workspace",
      "createdAt": "2024-01-10T08:00:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "d4e5f6a7",
      "name": "Warehouse Inventory",
      "status": "active",
      "workspaceId": "my-workspace",
      "createdAt": "2024-01-12T14:00:00.000Z",
      "updatedAt": "2024-01-15T09:00:00.000Z"
    }
  ],
  "lookbackDays": 14
}
```

{% endtab %}

{% tab title="403" %}

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

{% endtab %}
{% endtabs %}

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

ステータスを `inactive`に設定してユースケースをアーカイブします。アーカイブされたユースケースは既定で一覧から非表示になり、新しいイベントの取り込みを拒否します。

**必要なスコープ:** `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-2afefc06c784ca78eb7ec96a99bee48f8a2daaa5%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### パスパラメータ

* **`useCaseId`** (string, required): アーカイブするユースケースのID。

#### リクエスト例

```bash
curl -X POST "https://api.roboflow.com/vision-events/use-cases/a1b3c8e1/archive" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### レスポンス例

{% tabs %}
{% tab title="200" %}

```json
{
  "success": true
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "error": "ソリューションが見つかりません"
}
```

{% endtab %}

{% tab title="403" %}

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

{% endtab %}
{% endtabs %}

#### 注記

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

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

ステータスを `有効`.

**必要なスコープ:** `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-2afefc06c784ca78eb7ec96a99bee48f8a2daaa5%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### パスパラメータ

* **`useCaseId`** (string, required): アーカイブ解除するユースケースのID。

#### リクエスト例

```bash
curl -X POST "https://api.roboflow.com/vision-events/use-cases/a1b3c8e1/unarchive" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### レスポンス例

{% tabs %}
{% tab title="200" %}

```json
{
  "success": true
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "ソリューションはアーカイブされていません"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "error": "ソリューションが見つかりません"
}
```

{% endtab %}

{% tab title="403" %}

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

{% endtab %}
{% endtabs %}

#### 注記

* アーカイブ済みの `inactive` ステータスのユースケースのみアーカイブ解除できます。すでにアクティブなユースケースのアーカイブ解除を試みると、 `400` エラーが返されます。
* アーカイブ解除後、そのユースケースはアクティブな一覧に表示され、再び新しいイベントの取り込みを受け付けます。

## Python SDK

各Visionイベントはユースケースに関連付けられています。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"作成されたユースケース: {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>ワークスペース内の Vision Event ユースケースを一覧表示します。</td></tr><tr><td><code>vision_events_use_case_create</code></td><td>新しい Vision Event ユースケースを作成します。</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>