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

# 사용 사례

## 소개

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

## 웹 앱

### 사용 사례

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

#### 하나의 유스 케이스와 여러 유스 케이스를 사용할 때

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

**별도의 유스 케이스를 생성하세요** 메타데이터 구조가 근본적으로 다를 때. 예를 들면:

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

#### 유스 케이스 생성

**에이전트를 통해**

다음 [Roboflow Agent](https://docs.roboflow.com/agents/agents/roboflow-agent) 는 Vision 이벤트로 워크플로를 빌드할 때 유스 케이스를 자동으로 생성합니다. 적합한 기존 유스 케이스가 있으면 그 유스 케이스를 선택하고, 그렇지 않으면 설명한 사용 사례를 바탕으로 새 유스 케이스를 생성합니다. 에이전트에게 직접 새 유스 케이스 설정을 요청할 수도 있습니다.

**대시보드에서**

1. 다음으로 이동하세요: **Vision Events** 작업 공간의 왼쪽 사이드바에서
2. 클릭 **+ 유스 케이스 생성**
3. 유스 케이스 이름을 입력하세요

<figure><img src="/files/688dec6eb57c9c6e737f6af5d650dab23e6a6988" 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/ko/monitoring-and-analytics/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/e9936d62dd1fe9402a8fefad639d177cee3294ab" 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/ko/monitoring-and-analytics/vision-events.md#http-api) 에서 전체 세부 정보를 확인하세요.

## HTTP API

### 유스 케이스 생성

작업 공간에 새 유스 케이스를 만듭니다. 유스 케이스는 배포 맥락(예: "Manufacturing Line 1", "Warehouse Inventory")별로 Vision 이벤트를 정리하는 데 도움이 됩니다.

**필수 스코프:** `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-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": "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/ko/monitoring-and-analytics/vision-events/create-a-vision-event.md#http-api).

### 유스 케이스 업데이트

기존 유스 케이스의 이름 또는 상태를 업데이트합니다.

**필수 스코프:** `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-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": "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/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-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": "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 %}

### 유스 케이스 보관

유스 케이스를 `비활성`비활성으로 설정하여 보관합니다. 보관된 유스 케이스는 기본적으로 목록에서 숨겨지며 새 이벤트 수집을 거부합니다.

**필수 스코프:** `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-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/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-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).