사용 사례

Use Cases를 사용하여 목적별로 Vision Events를 그룹화합니다.

소개

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

웹 앱

사용 사례

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

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

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

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

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

유스 케이스 생성

에이전트를 통해

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

대시보드에서

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

REST API를 통해서도 유스 케이스를 생성할 수 있습니다. 다음을 참조하세요 프로그램 방식으로 유스 케이스 관리.

유스 케이스 보기

대시보드에서

Vision 이벤트 페이지에는 모든 유스 케이스의 표가 표시되며, 다음 항목이 포함됩니다:

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

API를 통해

작업 공간의 모든 유스 케이스를 가져오세요:

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

다음을 참조하세요 Vision Events API 레퍼런스 에서 전체 응답 형식을 확인하세요.

프로그램 방식으로 유스 케이스 관리

대시보드 외에도 REST API를 통해 유스 케이스를 생성, 이름 변경, 보관, 보관 해제할 수 있습니다. 이러한 엔드포인트에는 다음 권한이 있는 API 키가 필요합니다. vision-events:manage 스코프(제한이 없는 작업 공간 API 키는 기본적으로 접근 권한이 있습니다).

유스 케이스 생성

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

유스 케이스 이름 변경

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

유스 케이스 보관 또는 보관 해제

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"

유스 케이스 보관

더 이상 필요하지 않을 때 대시보드에서 유스 케이스를 보관할 수 있습니다. 보관된 유스 케이스와 그 이벤트는 계속 접근할 수 있지만 기본 보기에서는 숨겨집니다. 보려면 보관된 유스 케이스 보기 를 유스 케이스 표 하단에서 클릭하세요.

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

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

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

응답 예시:

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

다음을 참조하세요 Vision Events API 레퍼런스 에서 전체 세부 정보를 확인하세요.

HTTP API

유스 케이스 생성

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

필수 스코프: vision-events:manage

Create a Use Case

post

Create a new use case in your workspace.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Body

namestring · min: 1 · max: 256Required

A name for the use case. Must be unique within the workspace.

Responses

201

Use case created successfully.

application/json

idstringOptional

namestringOptional

400

Validation error or duplicate name.

application/json

403

Insufficient permissions for this resource.

application/json

post/vision-events/use-cases

POST /vision-events/use-cases HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "name": "text"
}

{
  "id": "text",
  "name": "text"
}

요청 본문 매개변수

이름 (문자열, 필수): 유스 케이스의 이름입니다. 1자 이상 256자 이하여야 합니다. 이름 앞뒤의 공백은 제거되며 작업 공간 내에서 고유해야 합니다.

예시 요청

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

예시 응답

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

{
  "error": "이 이름의 솔루션이 이미 존재합니다"
}

{
  "error": "이 리소스에 대한 권한이 충분하지 않습니다."
}

참고

새 유스 케이스는 기본적으로 활성 상태로 생성됩니다.
유스 케이스 이름은 작업 공간 내에서 고유해야 합니다. 기존 이름과 같은 유스 케이스를 만들려고 하면 400 오류가 반환됩니다.
유스 케이스를 생성한 후에는 id 를 useCaseId Vision 이벤트를 생성할 때 생성된 유스 케이스를 참조할 수 있습니다.

유스 케이스 업데이트

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

필수 스코프: vision-events:manage

Update a Use Case

put

Update the name or status of an existing use case.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

useCaseIdstringRequired

The ID of the use case to update.

Body

namestring · min: 1 · max: 256Optional

A new name for the use case. Must be unique within the workspace.

statusstring · enumOptional

The new status for the use case.

Possible values:

Responses

200

Use case updated successfully.

application/json

idstringOptional

namestringOptional

400

Validation error or duplicate name.

application/json

403

Insufficient permissions for this resource.

application/json

404

Use case not found.

application/json

put/vision-events/use-cases/{useCaseId}

PUT /vision-events/use-cases/{useCaseId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "name": "text",
  "status": "active"
}

{
  "id": "text",
  "name": "text"
}

경로 매개변수

useCaseId (문자열, 필수): 업데이트할 유스 케이스의 ID입니다.

요청 본문 매개변수

다음 필드 중 최소 하나를 제공해야 합니다:

이름 (문자열, 선택 사항): 유스 케이스의 새 이름입니다. 1자 이상 256자 이하여야 합니다. 작업 공간 내에서 고유해야 합니다.
상태 (문자열, 선택 사항): 새 상태입니다. 다음 중 하나 활성 또는 비활성.

예시 요청

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

예시 응답

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

{
  "error": "이 이름의 솔루션이 이미 존재합니다"
}

{
  "error": "솔루션을 찾을 수 없습니다"
}

{
  "error": "이 리소스에 대한 권한이 충분하지 않습니다."
}

사용 사례 목록 조회

작업 공간에서 Vision 이벤트가 기록된 모든 유스 케이스를 나열합니다. 유스 케이스를 생성하고 관리하는 방법을 알아보려면 다음을 참조하세요 사용 사례 문서.

필수 스코프: vision-events:read 또는 device:read

List Use Cases

get

List all use cases that have recorded vision events in your workspace.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Query parameters

statusstring · enumOptional

Filter by use case status. Defaults to active.

Default: activePossible values:

Responses

200

List of use cases.

application/json

lookbackDaysintegerOptional

403

Insufficient permissions for this resource.

application/json

get/vision-events/use-cases

GET /vision-events/use-cases HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "useCases": [
    {
      "id": "text",
      "name": "text",
      "status": "active",
      "workspaceId": "text",
      "createdAt": "2026-08-09T06:19:18.085Z",
      "updatedAt": "2026-08-09T06:19:18.085Z"
    }
  ],
  "lookbackDays": 1
}

쿼리 매개변수

상태 (문자열, 선택 사항): 유스 케이스 상태로 필터링합니다. 다음 중 하나 활성 또는 비활성. 기본값은 활성.

예시 요청

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

예시 응답

{
  "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
}

{
  "error": "이 리소스에 대한 권한이 충분하지 않습니다."
}

유스 케이스 보관

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

필수 스코프: vision-events:manage

Archive a Use Case

post

Archive a use case by setting its status to inactive.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

useCaseIdstringRequired

The ID of the use case to archive.

Responses

200

Use case archived successfully.

application/json

successbooleanOptional

403

Insufficient permissions for this resource.

application/json

404

Use case not found.

application/json

post/vision-events/use-cases/{useCaseId}/archive

POST /vision-events/use-cases/{useCaseId}/archive HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true
}

경로 매개변수

useCaseId (문자열, 필수): 보관할 유스 케이스의 ID입니다.

예시 요청

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

예시 응답

{
  "success": true
}

{
  "error": "솔루션을 찾을 수 없습니다"
}

{
  "error": "이 리소스에 대한 권한이 충분하지 않습니다."
}

참고

보관은 소프트 삭제입니다. 유스 케이스와 해당 이벤트는 보존되지만 활성 목록에서는 숨겨집니다.
보관된 유스 케이스를 보려면 사용 사례 목록 조회 엔드포인트를 status=inactive.
다음을 사용하여 보관된 유스 케이스를 복원할 수 있습니다 유스 케이스 보관 해제 엔드포인트.

유스 케이스 보관 해제

이전에 보관된 유스 케이스의 상태를 다시 활성.

필수 스코프: vision-events:manage

Unarchive a Use Case

post

Restore a previously archived use case by setting its status back to active.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Path parameters

useCaseIdstringRequired

The ID of the use case to unarchive.

Responses

200

Use case unarchived successfully.

application/json

successbooleanOptional

400

Use case is not archived.

application/json

403

Insufficient permissions for this resource.

application/json

404

Use case not found.

application/json

post/vision-events/use-cases/{useCaseId}/unarchive

POST /vision-events/use-cases/{useCaseId}/unarchive HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true
}

경로 매개변수

useCaseId (문자열, 필수): 보관 해제할 유스 케이스의 ID입니다.

예시 요청

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

예시 응답

{
  "success": true
}

{
  "error": "솔루션이 보관되지 않았습니다"
}

{
  "error": "솔루션을 찾을 수 없습니다"
}

{
  "error": "이 리소스에 대한 권한이 충분하지 않습니다."
}

참고

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

Python SDK

각 Vision 이벤트는 유스 케이스와 연결됩니다. Python SDK는 유스 케이스를 생성, 나열, 이름 변경, 보관, 보관 해제하는 메서드를 제공합니다.

사용 사례 목록 조회

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

상태로 필터링할 수 있습니다:

# 활성 유스 케이스만 나열
result = ws.list_vision_event_use_cases(status="active")

유스 케이스 생성

result = ws.create_vision_event_use_case("manufacturing-qa")
use_case_id = result["id"]
print(f"생성된 유스 케이스: {use_case_id}")

유스 케이스 이름 변경

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

유스 케이스 보관

ws.archive_vision_event_use_case("a1b3c8e1")

유스 케이스 보관 해제

ws.unarchive_vision_event_use_case("a1b3c8e1")

유스 케이스 관리에 대한 자세한 내용은 다음을 참조하세요 REST API 참조.

이전Vision Event 이미지 업로드 다음액티브 러닝

마지막 업데이트 9일 전

도움이 되었나요?