> 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/datasets/ko/create-and-upload/adding-data/datasources.md).

# 데이터 소스

외부 저장소의 이미지와 메타데이터를 Roboflow 워크스페이스에 자동으로 동기화합니다.

데이터 소스를 사용하면 클라우드 스토리지의 이미지와 메타데이터를 Roboflow 에셋 라이브러리에 지속적으로 미러링할 수 있습니다. 미러링된 이미지는 의미, 사용자 지정 메타데이터, 태그 또는 이미지 유사성으로 검색할 수 있으며, 라벨링과 학습을 위해 모든 프로젝트에 추가할 수 있습니다.

현재 AWS S3, S3 호환 스토리지, Google Cloud Storage, Azure Blob Storage 버킷 미러링을 지원합니다.

{% hint style="warning" %}
원본 데이터가 AWS S3, Google Cloud Storage 또는 Azure Blob Storage와 같은 클라우드 스토리지에 있다면 데이터 소스와 버킷 미러를 기본 경로로 사용하여 Roboflow로 가져오고 수집한 뒤 동기화하세요. 서명된 URL 업로드나 로컬 다운로드 워크플로는 일회성 또는 임시 가져오기에만 사용하세요.
{% endhint %}

## 버킷 미러의 작동 방식

데이터 소스를 구성하면 Roboflow가 버킷을 탐색하고 조건에 맞는 모든 이미지 파일을 워크스페이스의 [에셋 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library).

* 지원 이미지 형식: JPEG, PNG, BMP, WebP, AVIF
* 워크스페이스에 이미 있는 파일(버킷 위치와 해시로 확인)은 다시 가져오지 않으므로 이그레스 비용이 줄어듭니다.
* 이미지와 같은 기본 이름을 가진 `.json` 사이드카 파일이 있으면 해당 파일의 메타데이터를 가져옵니다. 중첩된 키는 점 표기법으로 평탄화됩니다(예: `capture.temperature`) - 자세한 내용은 [메타데이터 사이드카](#metadata-sidecars)
* 버킷에서 사라진 파일은 기본적으로 보존됩니다. 대신 삭제하려면 고아 파일 제거를 사용 설정하세요(자세한 내용은 [고아 파일 제거](#removing-orphaned-files))

### 업로드 심사

워크스페이스에서 업로드 시 자동화를 통해 업로드를 심사하는 경우, 각 동기화 작업에서 새 이미지는 심사를 위해 보류됩니다. 심사에서 허용하거나 수정 조치를 한 후에만 이미지가 표시됩니다. 거부된 이미지는 가져오지 않으며 이후 동기화에서도 건너뜁니다. 가져온 이미지의 파일이 변경되면 심사를 거치지 않고 해당 이미지가 제자리에서 업데이트됩니다.

실행 세부 정보에 보류 및 건너뛴 항목 수가 표시됩니다. [동기화 시](https://docs.roboflow.com/deployment/roboflow-cloud/batch-processing) 워크플로 실행은 보류된 각 이미지에 판정이 내려질 때까지 최대 24시간 대기합니다.

### 동영상

Roboflow는 MP4 및 QuickTime(`.mov`) 동영상도 미러링하며, 파일당 최대 크기는 3GB입니다. 동영상은 에셋 라이브러리에만 저장되며 프로젝트에 추가되지 않고 프레임도 추출되지 않습니다. 동영상은 이미지와 동일한 방식으로 `.json` 사이드카 메타데이터를 읽습니다. 동영상을 제외하려면 이미지 파일만 일치하는 glob 패턴을 사용하세요.

## 버킷을 Roboflow에 미러링하기

### 필수 조건

1. 이미지 데이터가 포함된 클라우드 스토리지 버킷(AWS S3, Google Cloud Storage 또는 Azure Blob Storage)
2. 해당 버킷에서 읽을 수 있는 재사용 가능한 Roboflow 자격 증명. 자세한 내용은 [데이터 소스 자격 증명](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasource-credentials.md)을 참조한 후 다음 안내를 따르세요: [AWS S3 자격 증명](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasource-credentials/aws-s3.md), [Google Cloud Storage 자격 증명](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasource-credentials/gcs.md)또는 [Azure Blob Storage 자격 증명](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasource-credentials/azure.md).

### Roboflow에서 자격 증명 추가하기

Roboflow는 버킷 액세스 정보를 재사용 가능한 자격 증명으로 안전하게 암호화하여 저장합니다. 제공업체별 설정 단계와 최소 권한 적용 지침은 다음을 참조하세요: [AWS S3 자격 증명](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasource-credentials/aws-s3.md), [Google Cloud Storage 자격 증명](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasource-credentials/gcs.md)또는 [Azure Blob Storage 자격 증명](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasource-credentials/azure.md).

워크스페이스 설정에서 [자격 증명](https://app.roboflow.com/settings/thirdpartykeys) 으로 이동한 다음 [자격 증명 추가](https://app.roboflow.com/settings/thirdpartykeys#create).

### 버킷 미러링을 위한 데이터 소스 구성하기

[새 데이터 소스 만들기](https://app.roboflow.com/settings/datasources) 를 워크스페이스 설정에서 선택하세요. 양식에는 두 개의 탭이 있습니다:

* "연결"에는 버킷 정보와 액세스 정보(이름, 공급자, 버킷, 리전, 자격 증명)가 포함됩니다. "자격 증명" 드롭다운에서 저장된 자격 증명을 선택하거나, 옆의 "+"를 사용해 양식을 벗어나지 않고 추가하세요.
* "미러 구성"에는 가져오기 대상, 파일 필터, 미러 동작이 포함됩니다.

"버킷" 필드에는 버킷 이름만 입력해야 합니다(예: `my-bucket`, `s3://my-bucket`). 이름 뒤에 경로가 포함된 버킷 값은 거부됩니다. 버킷의 일부만 미러링하려면 "미러 구성" 탭의 "파일 필터"에 다음과 같은 glob 패턴을 추가하세요. `images/**/*` Azure Blob Storage에서도 컨테이너 이름에 같은 규칙이 적용됩니다.

### 가져오기 대상 선택

"미러 구성" 아래의 "가져오기 대상" 섹션에서 미러링한 파일을 저장할 위치를 설정합니다. 각 데이터 소스는 하나의 대상에만 가져옵니다. 다른 위치로 가져오려면 데이터 소스를 추가하세요.

* "워크스페이스"는 다음 위치로 미러링합니다. [에셋 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library). "가져오기 위치" 드롭다운에서 파일을 워크스페이스 루트에 저장하거나, 프로젝트를 선택해 해당 프로젝트에도 추가할 수 있습니다.
* "폴더"는 미러링한 이미지를 프로젝트 폴더로 제한하여 해당 폴더의 팀원만 볼 수 있도록 합니다. 이 옵션은 다음 기능이 포함된 요금제에서 사용할 수 있습니다. [프로젝트 폴더 권한](https://docs.roboflow.com/datasets/ko/manage/project-folders/project-folder-permissions.md).

### Glob 패턴으로 필터링

기본적으로 버킷에 있는 지원되는 모든 이미지 파일을 가져옵니다. 가져올 파일은 glob 패턴을 직접 지정하거나 버킷에 저장된 `.txt` 파일을 사용해 제한할 수 있습니다.

glob 패턴 대신 파일 경로의 명시적 허용 목록을 제공할 수도 있습니다.

### 패턴 의미

* `*` 다음을 제외한 모든 문자와 일치합니다. `/` (단일 디렉터리 수준)
* `**` 다음을 포함한 모든 문자와 일치합니다. `/` (여러 디렉터리 수준)

### 예시

**접두사로 일치:**

```
harvest**
```

일치 항목: `harvest`, `harvest2024`, `harvest/sun/file.jpg`, `harvest-data.png`\
일치하지 않는 항목: `Harvest`, `my-harvest`

**폴더의 모든 항목과 일치:**

```
/harvest/sun/**
```

일치 항목: `/harvest/sun/file.txt`, `/harvest/sun/subfolder/image.jpg`, `/harvest/sun/deep/nested/path/data.png`\
일치하지 않는 항목: `/harvest/moon/file.txt`, `/other/sun/file.txt`

**하위 트리에서 접미사로 일치:**

```
/planting/**/*crops.png
```

일치 항목: `/planting/wheat-crops.png`, `/planting/subfolder/rice-crops.png`\
일치하지 않음: `/planting/wheat.png`, `/other/wheat-crops.png`

**특정 디렉터리 수준에서 이름 패턴으로 일치시키기:**

```
/*/a/**/*weed*2025-10-27.png
```

일치함: `/farm/a/field/weed-2025-10-27.png`, `/garden/a/plot/seaweed-data-2025-10-27.png`\
일치하지 않음: `/farm/b/field/weed-2025-10-27.png`

**정확한 경로:**

```
/exact/path/to/file.jpg
```

해당 파일만 일치합니다.

**파일 이름에 와일드카드 문자를 그대로 사용하려면:**\
패턴을 따옴표로 감싸면 `*` 문자를 그대로 취급합니다:

```
"/path/to/file*.jpg"
```

### 고아 파일 제거

고아 파일 제거는 기본적으로 사용 중지되어 있으므로 버킷에서 사라진 파일도 유지됩니다.  `removeOrphanedSourcesWhenDisappeared` 활성화되어 있으면 버킷에 더 이상 존재하지 않는 파일(또는 글롭 패턴과 더 이상 일치하지 않는 파일)은 어떤 프로젝트나 다른 데이터 소스 구성에서도 참조되지 않는 경우 Roboflow 워크스페이스에서 제거됩니다.

데이터 소스를 삭제할 때도 이 설정이 적용됩니다. 고아 파일 제거가 활성화되어 있고 버킷이 한 번 이상 미러링된 경우, 해당 버킷에서 가져왔으며 다른 프로젝트에서 사용하지 않는 이미지는 정리 작업자가 제거할 수 있습니다. 삭제 확인 대화상자에 이 내용이 표시되며, 삭제를 진행하기 전에 명시적으로 확인해야 합니다. 이를 방지하려면 데이터 소스를 삭제하기 전에 미러 구성에서 고아 파일 제거를 비활성화하세요.

### 파일 이름 지정

&#x20;`namingStrategy`  설정은 가져온 파일의 이름을 지정하고 Roboflow에 표시하는 방식을 제어합니다:

| 전략         | 설명                                                         |
| ---------- | ---------------------------------------------------------- |
| `fullPath` | 전체 S3 키 경로를 파일 이름으로 사용합니다(기본값)                             |
| `fileName` | S3 키에서 파일 이름 부분만 사용합니다                                     |
| `eTag`     | S3 객체의 ETag를 사용합니다                                         |
| `metadata` | 이미지 메타데이터에서 지정된 값을 사용합니다: `namingStrategyMetadataKey` (필수) |

### 이미지 업데이트

S3의 이미지가 수정되면 Roboflow가 워크스페이스의 사본을 업데이트할 수 있습니다:

* `updateImageWhenNewer` (기본값: `true`) - S3 객체가 저장된 버전보다 최신이면 이미지를 다시 가져옵니다
* `updateImageStrategy` - 업데이트 적용 방식을 제어합니다. 현재 지원되는 방식은 `overwrite` (기존 이미지를 대체)입니다

### 메타데이터 사이드카

이미지에 메타데이터를 첨부하려면 다음을 배치합니다 `.json` 각 이미지와 함께 버킷에 저장하는 사이드카 파일입니다. 파일 이름은 이미지와 동일한 기본 이름을 사용합니다.

```
my-bucket/
  images/
    photo_001.jpg
    photo_001.json      # photo_001.jpg의 메타데이터
    photo_002.jpg
    photo_002.json      # photo_002.jpg의 메타데이터
```

사이드카 파일에는 키-값 쌍이 포함됩니다.

```json
{
  "camera_id": "cam001",
  "location": "warehouse-3",
  "capture": { "temperature": 72.5, "humidity": 45 }
}
```

중첩된 객체는 점 표기법을 사용해 평탄화됩니다. 위 예시의 결과는 다음과 같습니다.

| 키                     | 값               |
| --------------------- | --------------- |
| `camera_id`           | `"cam001"`      |
| `location`            | `"warehouse-3"` |
| `capture.temperature` | `72.5`          |
| `capture.humidity`    | `45`            |

사이드카 파일 제약 조건:

* 최대 파일 크기: 256KB
* 유효한 JSON이어야 합니다
* `null` 및 `undefined` 값은 필터링됩니다

### 메타데이터 동기화 전략

이미지의 메타데이터 사이드카 `.json` 파일이 S3에서 업데이트되면, 업데이트 적용 방식은 다음 두 설정으로 제어합니다.

* `updateMetadataWhenNewer` (기본값: `true`) - 사이드카 파일이 저장된 버전보다 최신이면 메타데이터를 다시 동기화합니다.
* `updateMetadataStrategy` - 동기화된 메타데이터를 UI 또는 API에서 직접 설정한 메타데이터와 결합하는 방식을 제어합니다.

| 전략                      | 동작                                                       |
| ----------------------- | -------------------------------------------------------- |
| `mergeBucketWins` (기본값) | 두 소스를 병합합니다. 키가 충돌하면 버킷의 값이 우선합니다.                       |
| `mergeUserWins`         | 두 소스를 병합합니다. 키가 충돌하면 사용자가 설정한 값이 우선합니다.                  |
| `overwrite`             | 버킷 메타데이터가 기존 메타데이터를 모두 완전히 대체합니다.                        |
| `untilFirstChange`      | 사용자가 메타데이터 필드를 하나라도 직접 수정할 때까지 버킷에서 동기화한 다음, 동기화를 중지합니다. |
| `append`                | 버킷의 새 키만 추가하며 기존 키를 덮어쓰지 않습니다.                           |

## 미러링 트리거하기

언제든지 다음에서 수동으로 미러링을 트리거할 수 있습니다. [데이터 소스 목록](https://app.roboflow.com/settings/datasources) 데이터 소스 옆의 재생 버튼을 클릭하면 됩니다.

수동 트리거에는 다음 제한이 적용됩니다.

* **진행 중**: 동기화가 이미 실행 중이면 완료될 때까지 다른 동기화를 시작할 수 없습니다.
* **대기 시간**: 동기화가 완료된 후 15분 동안 수동으로 다시 트리거할 수 없습니다. 버튼의 툴팁에 남은 시간이 표시됩니다. 다음과 같은 경우에는 대기 시간이 적용되지 않습니다.
  * 이전 동기화에서 가져올 새 항목을 찾지 못한 경우(대기열에 추가된 파일이 없거나 모든 파일의 처리에 실패한 경우).
  * 마지막 실행 이후 데이터 소스 구성을 수정한 경우.
  * 마지막 실행이 오류와 함께 완료된 경우.
* **시간당 제한**: 데이터 소스는 이동 기준 1시간 동안 최대 10회 동기화할 수 있습니다. 대기 시간 예외가 적용되어 즉시 다시 트리거할 수 있는 경우에도 이 제한은 적용됩니다.

예약된(cron) 동기화에는 대기 시간과 시간당 제한이 모두 적용되지 않습니다.

### 일정에 따라 매일 실행하기

자동으로 미러링하려면 "미러 구성" 탭의 "예약" 섹션을 열고 "매일 일정에 따라 자동 실행"을 선택하세요. 그러면 데이터 소스가 24시간마다 동기화됩니다. 기본적으로 예약 기능은 꺼져 있습니다.

## 동기화된 에셋 보기

각 [데이터 소스 항목](https://app.roboflow.com/settings/datasources) 에는 눈 모양 아이콘이 있으며, 이 아이콘을 클릭하면 [에셋 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library) 에서 해당 데이터 소스의 이미지와 동영상만 볼 수 있습니다. 데이터 소스가 한 번 이상 동기화를 완료하기 전까지는 아이콘이 비활성화되어 있습니다.

어떤 데이터 소스에서든 동기화된 모든 이미지를 보려면 데이터 소스 목록 하단의 "데이터 소스 에셋 보기"를 클릭하세요. 데이터 소스가 하나 이상 실행된 후에 이 링크가 표시됩니다.

두 링크 모두 태그 필터가 미리 적용된 에셋 라이브러리로 이동하므로, 버킷에서 미러링된 워크스페이스 이미지 하위 집합만 탐색하고 검색하며 관리할 수 있습니다.

## S3 호환 스토리지

데이터 소스는 필요한 S3 API 작업을 구현하는 S3 호환 스토리지 제공업체와 함께 사용할 수 있습니다.

이러한 제공업체 중 하나를 구성하려면 다음 단계를 따르세요.

1. 데이터 소스의 "연결" 탭에서 `S3` 를 제공업체로 선택합니다.
2. 평소와 같이 버킷 이름과 자격 증명을 입력합니다.
3. 제공업체의 사용자 지정 `endpoint` URL을 지정합니다.
4. 리전을 `auto` 또는 제공업체별 리전 값으로 설정합니다.

제공업체의 S3 API 엔드포인트를 `endpoint`로 사용하세요. CDN URL, 공개 버킷 URL 또는 브라우저 다운로드 URL은 사용하지 마세요.

엔드포인트는 공용 인터넷에서 연결할 수 있어야 합니다. Roboflow는 `localhost`나 사설 네트워크 주소 또는 링크-로컬 주소를 가리키는 엔드포인트를 거부하며, 해당 주소로 확인되는 호스트 이름도 거부합니다.

동일한 glob 패턴 필터링, 메타데이터 사이드카 동작 및 미러 설정도 이러한 제공업체에서 사용할 수 있습니다.

### 경로 스타일 주소 지정

일부 제공업체는 버킷 이름을 호스트 이름(`endpoint/bucket/key`)이 아니라 URL 경로(`bucket.endpoint/key`). 엔드포인트를 입력하면 "연결" 탭에 "경로 스타일 주소 지정 사용" 체크박스가 표시됩니다. Roboflow는 엔드포인트에 맞는 설정을 미리 선택하며, 설정을 변경한 경우에도 선택한 값을 유지합니다.

MinIO를 비롯한 자체 호스팅 게이트웨이 또는 NAS 게이트웨이, Oracle Cloud 호환 엔드포인트, IP 주소나 포트로 접속하는 엔드포인트, 이름에 마침표가 포함된 버킷에서는 이 옵션을 켜세요. 가상 호스트 방식 URL을 제공하는 공급자(예: Cloudflare R2, Backblaze B2, Wasabi, DigitalOcean Spaces, Alibaba Cloud OSS)에서는 끄세요. 잘못된 설정을 사용하면 파일 목록을 가져오는 중 연결 테스트가 실패하며, 오류 메시지에 설정을 전환하라는 안내가 표시됩니다.

지원되는 S3 호환 스토리지 공급자는 다음과 같습니다.

| 공급자                                               | 엔드포인트 호스트 이름 예시                                    |
| ------------------------------------------------- | -------------------------------------------------- |
| Cloudflare R2                                     | `<account-id>.r2.cloudflarestorage.com`            |
| Backblaze B2                                      | `s3.<region>.backblazeb2.com`                      |
| DigitalOcean Spaces                               | `<region>.digitaloceanspaces.com`                  |
| Akamai Linode Object Storage                      | `<region>.linodeobjects.com`                       |
| Wasabi                                            | `s3.<region>.wasabisys.com`                        |
| Vultr Object Storage                              | `<region>.vultrobjects.com`                        |
| OVHcloud Object Storage                           | `s3.<region>.io.cloud.ovh.net`                     |
| Scaleway Object Storage                           | `s3.<region>.scw.cloud`                            |
| Open Telekom Cloud                                | `obs.<region>.otc.t-systems.com`                   |
| Exoscale SOS                                      | `sos-<region>.exo.io`                              |
| IONOS Cloud Object Storage                        | `s3-<region>.ionoscloud.com`                       |
| IBM Cloud Object Storage                          | `s3.<region>.cloud-object-storage.appdomain.cloud` |
| Oracle Cloud Infrastructure Object Storage S3 호환성 | `compat.objectstorage.<region>.oraclecloud.com`    |
| Seagate Lyve Cloud                                | `s3.<region>.lyvecloud.seagate.com`                |
| Huawei Cloud OBS                                  | `obs.<region>.myhuaweicloud.com`                   |
| Alibaba Cloud OSS                                 | `oss-<region>.aliyuncs.com`                        |
| Tencent Cloud COS                                 | `cos.<region>.myqcloud.com`                        |
| Yandex Object Storage                             | `storage.yandexcloud.net`                          |
| Storj Hosted S3 Gateway                           | `gateway.storjshare.io`                            |

## 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>connect_cloud_storage</code></td><td>자격 증명 설정부터 첫 실행까지 버킷 미러링을 처음부터 끝까지 설정합니다.</td></tr><tr><td><code>credentials_create</code></td><td>클라우드 스토리지 자격 증명을 생성합니다.</td></tr><tr><td><code>credentials_list</code></td><td>워크스페이스의 클라우드 스토리지 자격 증명을 나열합니다.</td></tr><tr><td><code>datasource_create</code></td><td>버킷 경로를 프로젝트에 미러링하는 데이터 소스를 생성합니다.</td></tr><tr><td><code>datasource_validate</code></td><td>Roboflow가 버킷에 접근할 수 있는지 확인합니다.</td></tr><tr><td><code>datasource_trigger</code></td><td>미러링 실행을 시작합니다.</td></tr><tr><td><code>datasource_job_get</code></td><td>미러링 실행 하나의 상태와 통계를 가져옵니다.</td></tr></tbody></table>
