> 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/ko/monitoring-and-analytics/vision-events/use-cases.md).

# Use Case

## 소개

하나의 Use Case는 [비전 이벤트](/deployment/ko/monitoring-and-analytics/vision-events.md) 공통 목적과 사용자 지정 메타데이터 구조를 공유하며, 각 이벤트는 정확히 하나의 Use Case에 속합니다. 이벤트를 이렇게 구성하면 동일한 필드를 보고하는 카메라, 장치, 위치 전반에서 데이터를 쉽게 필터링하고 비교할 수 있습니다. 이 페이지에서는 하나의 Use Case를 사용할 때와 여러 개를 사용할 때를 구분하는 방법과, 이를 생성하고 관리하는 방법을 설명합니다.

## 웹 앱

### 사용 사례

하나의 Use Case는 공통 목적과 사용자 지정 메타데이터 구조를 공유하는 Vision 이벤트를 그룹화합니다. 각 이벤트는 정확히 하나의 Use Case에 속합니다. 동일한 Use Case의 이벤트는 일반적으로 같은 메타데이터 필드를 공유하므로, 서로 다른 소스의 데이터를 쉽게 필터링하고 비교할 수 있습니다.

#### 하나의 Use Case를 사용할 때 vs. 여러 Use Case를 사용할 때

**이벤트를 같은 Use Case에 넣으세요** 서로 다른 위치, 카메라 또는 장치에서 오더라도 유사한 사용자 지정 메타데이터 필드를 공유할 때. 예를 들어, "Defect Detection" Use Case는 여러 공장에서 오는 이벤트를 받을 수 있지만, 모든 이벤트에는 `line_id`, `shift`, 그리고 `part_number`.

**별도의 Use Case를 만드세요** 메타데이터 구조가 근본적으로 다를 때. 예를 들면:

* **조립 라인 QA** - 추적 `line_id`, `shift`, `part_number`
* **창고 재고** - 추적 `통로`, `선반`, `항목 유형`
* **건설 현장 안전** - 추적 `zone`, `alert_type`, `시공업체`

#### Use Case 만들기

**에이전트를 통해**

에이전트는 [Roboflow 에이전트](https://docs.roboflow.com/agents/roboflow-agent) Vision 이벤트로 워크플로를 만들 때 Use Case를 자동으로 생성합니다. 설명한 사용 사례에 따라 적합한 기존 Use Case가 있으면 선택하고, 없으면 새로 만듭니다. 에이전트에게 직접 새 Use Case를 설정해 달라고 요청할 수도 있습니다.

**대시보드에서**

1. 다음으로 이동 **비전 이벤트** 작업 공간의 왼쪽 사이드바에서
2. 클릭 **+ Use Case 만들기**
3. Use Case 이름을 입력하세요

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

REST API를 통해서도 Use Case를 만들 수 있습니다. 다음을 참조하세요. [Use Case 프로그래밍 방식으로 관리](#manage-use-cases-programmatically).

#### Use Case 보기

**대시보드에서**

Vision 이벤트 페이지에는 모든 Use Case의 표가 표시되며, 다음을 보여줍니다:

* Use Case 이름
* 총 이벤트 수
* 마지막 이벤트 타임스탬프
* 사용 중인 이벤트 유형

**API를 통해**

작업 공간의 모든 Use Case를 가져옵니다:

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

다음을 참조하세요 [Vision Events API 참조](/deployment/ko/monitoring-and-analytics/vision-events.md#http-api) 전체 응답 형식을 보려면.

#### Use Case 프로그래밍 방식으로 관리

대시보드 외에도 REST API를 통해 Use Case를 만들고, 이름을 바꾸고, 보관하고, 보관 해제할 수 있습니다. 이러한 엔드포인트에는 다음 범위가 있는 API 키가 필요합니다. `vision-events:manage` 범위(제한 없는 작업 공간 API 키는 기본적으로 액세스 권한이 있습니다).

**Use Case 만들기**

```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" }'
```

**Use Case 이름 바꾸기**

```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" }'
```

**Use Case 보관 또는 보관 해제**

```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"
```

#### Use Case 보관

Use Case는 더 이상 필요하지 않을 때 대시보드에서 보관할 수 있습니다. 보관된 Use Case와 해당 이벤트는 계속 접근 가능하지만 기본 보기에서는 숨겨집니다. 보려면 **보관된 Use Case 보기** 을 Use Case 표 하단에서 클릭하세요.\ <br>

<figure><img src="/files/e9936d62dd1fe9402a8fefad639d177cee3294ab" alt=""><figcaption></figcaption></figure>

#### 사용자 지정 메타데이터 스키마

이벤트가 Use Case로 전송된 후 시스템은 관찰된 필드와 값 유형을 기반으로 메타데이터 스키마를 추론합니다. Use Case의 추론된 스키마를 가져와 어떤 키와 값 유형이 사용 중인지 확인할 수 있습니다:

```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/ko/monitoring-and-analytics/vision-events.md#http-api) 전체 세부 정보를 보려면.

## HTTP API

### Use Case 만들기

작업 공간에 새 Use Case를 만드세요. Use Case는 배포 상황별로 Vision 이벤트를 정리하는 데 도움이 됩니다(예: "Manufacturing Line 1", "Warehouse Inventory").

**필요한 스코프:** `vision-events:manage`

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases" method="post" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-2afefc06c784ca78eb7ec96a99bee48f8a2daaa5%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### 요청 본문 매개변수

* **`name`** (문자열, 필수): Use Case의 이름입니다. 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 %}

#### 참고

* 새 Use Case는 `활성` 상태로 기본 생성됩니다.
* Use Case 이름은 작업 공간 내에서 고유해야 합니다. 기존 Use Case와 같은 이름으로 만들려고 하면 `400` 오류가 반환됩니다.
* Use Case를 만든 후에는 해당 `id` 를 `useCaseId` 로 [Vision 이벤트를 생성할 때](/deployment/ko/monitoring-and-analytics/vision-events/create-a-vision-event.md#http-api).

### Use Case 업데이트

기존 Use Case의 이름이나 상태를 업데이트합니다.

**필요한 스코프:** `vision-events:manage`

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases/{useCaseId}" method="put" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-2afefc06c784ca78eb7ec96a99bee48f8a2daaa5%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### 경로 매개변수

* **`useCaseId`** (문자열, 필수): 업데이트할 Use Case의 ID입니다.

#### 요청 본문 매개변수

다음 필드 중 하나 이상을 제공해야 합니다:

* **`name`** (문자열, 선택 사항): Use Case의 새 이름입니다. 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": "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 이벤트를 기록한 모든 Use Case를 나열합니다. Use Case를 만들고 관리하는 방법을 알아보려면 [사용 사례 문서](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md).

**필요한 스코프:** `vision-events:read` 또는 `device:read`

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases" method="get" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-2afefc06c784ca78eb7ec96a99bee48f8a2daaa5%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### 쿼리 매개변수

* **`상태`** (문자열, 선택 사항): Use Case 상태로 필터링합니다. 다음 중 하나여야 합니다. `활성` 또는 `비활성`. 기본값은 `활성`.

#### 요청 예시

```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 %}

### Use Case 보관

상태를 다음으로 설정하여 Use Case를 보관하세요 `비활성`. 보관된 Use Case는 기본적으로 목록에서 숨겨지며 새 이벤트 수집을 거부합니다.

**필요한 스코프:** `vision-events:manage`

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases/{useCaseId}/archive" method="post" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-2afefc06c784ca78eb7ec96a99bee48f8a2daaa5%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### 경로 매개변수

* **`useCaseId`** (문자열, 필수): 보관할 Use Case의 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 %}

#### 참고

* 보관은 소프트 삭제입니다. Use Case와 해당 이벤트는 보존되지만 활성 목록에서는 숨겨집니다.
* 보관된 Use Case를 보려면 [사용 사례 목록](#http-api) 엔드포인트를 `status=inactive`.
* 보관된 Use Case는 다음을 사용하여 복원할 수 있습니다. [Use Case 보관 해제](#http-api) 엔드포인트.

### Use Case 보관 해제

상태를 다음으로 되돌려 이전에 보관된 Use Case를 복원합니다 `활성`.

**필요한 스코프:** `vision-events:manage`

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases/{useCaseId}/unarchive" method="post" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-2afefc06c784ca78eb7ec96a99bee48f8a2daaa5%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### 경로 매개변수

* **`useCaseId`** (문자열, 필수): 보관 해제할 Use Case의 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 %}

#### 참고

* 상태인 Use Case만 `비활성` 보관 해제할 수 있습니다. 이미 활성 상태인 Use Case를 보관 해제하려고 하면 `400` 오류가 반환됩니다.
* 보관 해제되면 Use Case는 활성 목록에 표시되고 새 이벤트 수집을 다시 허용합니다.

## Python SDK

각 Vision 이벤트는 하나의 Use Case와 연결됩니다. Python SDK는 Use Case를 만들고, 나열하고, 이름을 바꾸고, 보관하고, 보관 해제하는 메서드를 제공합니다.

### 사용 사례 목록

```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
# 활성 Use Case만 나열
result = ws.list_vision_event_use_cases(status="active")
```

### Use Case 만들기

```python
result = ws.create_vision_event_use_case("manufacturing-qa")
use_case_id = result["id"]
print(f"생성된 Use Case: {use_case_id}")
```

### Use Case 이름 바꾸기

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

### Use Case 보관

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

### Use Case 보관 해제

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

Use Case 관리에 대한 자세한 내용은 [REST API 참조](#http-api).

## MCP 서버

AI 에이전트를 [MCP 서버](https://docs.roboflow.com/agents/mcp-server) 를 참조하세요. 또한 다음 도구로 Use Case를 관리할 수 있습니다:

<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>기존 Use Case의 이름을 변경합니다.</td></tr><tr><td><code>vision_events_use_case_archive</code></td><td>Use Case를 보관합니다.</td></tr><tr><td><code>vision_events_use_case_unarchive</code></td><td>이전에 보관된 Use Case를 복원합니다.</td></tr></tbody></table>