> 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).

# ユースケース

## 概要

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

## Web アプリ

### ユースケース

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

#### 1つのユースケースを使う場合と複数のユースケースを使う場合

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

**ユースケースを分けて作成する** メタデータ構造が根本的に異なる場合です。たとえば:

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

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

**Agent経由で**

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

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

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 を使用してユースケースの作成、名前変更、アーカイブ、アーカイブ解除ができます。これらのエンドポイントには、次の権限を持つ API キーが必要です: `vision-events:manage` スコープ（制限なしのワークスペース 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

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

ワークスペースに新しいユースケースを作成します。ユースケースは、展開コンテキスト（例:「製造ライン 1」「倉庫在庫」）ごとにVisionイベントを整理するのに役立ちます。

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

#### リクエストボディのパラメータ

* **`名前`** （文字列、必須）: ユースケースの名前。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": "製造ライン 1"
  }'
```

#### レスポンス例

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

```json
{
  "id": "a1b3c8e1",
  "name": "製造ライン 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-dfdc1702ad3d1a62ad0a661e9609f6bbe2fc8d4c%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### パスパラメータ

* **`useCaseId`** （文字列、必須）: 更新するユースケースのID。

#### リクエストボディのパラメータ

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

* **`名前`** （文字列、任意）: ユースケースの新しい名前。1〜256文字である必要があります。ワークスペース内で一意でなければなりません。
* **`状態`** （文字列、任意）: 新しいステータス。次のいずれかです: `アクティブ` または `非アクティブ`.

#### リクエスト例

```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": "製造ライン 2"
  }'
```

#### レスポンス例

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

```json
{
  "id": "a1b3c8e1",
  "name": "製造ライン 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-dfdc1702ad3d1a62ad0a661e9609f6bbe2fc8d4c%2Fopenapi.yaml?alt=media)
{% endopenapi %}

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

* **`状態`** （文字列、任意）: ユースケースのステータスでフィルタします。次のいずれかです: `アクティブ` または `非アクティブ`。既定値は `アクティブ`.

#### リクエスト例

```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": "製造ライン 1",
      "status": "アクティブ",
      "workspaceId": "my-workspace",
      "createdAt": "2024-01-10T08:00:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "d4e5f6a7",
      "name": "倉庫在庫",
      "status": "アクティブ",
      "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 %}

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

ユースケースは、そのステータスを `非アクティブ`に設定することでアーカイブできます。アーカイブ済みのユースケースは、既定で一覧から非表示になり、新しいイベントの取り込みを拒否します。

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

#### パスパラメータ

* **`useCaseId`** （文字列、必須）: アーカイブするユースケースの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-dfdc1702ad3d1a62ad0a661e9609f6bbe2fc8d4c%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### パスパラメータ

* **`useCaseId`** （文字列、必須）: アーカイブ解除するユースケースの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 %}

#### 注意事項

* アーカイブ解除できるのは、 `非アクティブ` ステータスを持つユースケースのみです。すでにアクティブなユースケースのアーカイブ解除を試みると、 `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).