> 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 자산 라이브러리로 지속적으로 미러링할 수 있습니다. 한 번 미러링되면 이미지는 의미, 사용자 지정 메타데이터, 태그 또는 이미지 유사성으로 검색할 수 있으며, 라벨링과 학습을 위해 어떤 프로젝트에든 추가할 수 있습니다.

현재는 AWS S3 및 S3 호환 스토리지 버킷 미러링을 지원합니다. Azure Blob Storage와 Google Cloud Storage 지원은 곧 제공됩니다.

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

## 버킷 미러 작동 방식

데이터 소스를 구성하면 Roboflow가 S3 버킷을 크롤링하여 일치하는 모든 이미지 파일을 작업 공간의 [자산 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library).

* 지원되는 이미지 형식: JPEG, PNG, BMP, WebP, AVIF
* 작업 공간에 이미 있는 파일(S3 위치와 해시가 일치하는 파일)은 다시 가져오지 않아 이그레스 비용이 줄어듭니다
* 만약 `.json` 사이드카 파일이 동일한 기본 이름의 이미지 옆에 있으면 해당 메타데이터가 가져와집니다. 중첩된 키는 점 표기법으로 평탄화됩니다(예: `capture.temperature`) - [메타데이터 사이드카](#metadata-sidecars)
* 버킷에서 사라진 파일은 기본적으로 유지됩니다. 대신 삭제하려면 고아 제거를 활성화하세요(참조: [고아 파일 제거](#removing-orphaned-files))

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

### 사전 요구 사항

1. 이미지 데이터를 포함하는 AWS S3 버킷
2. 해당 버킷에서 읽을 수 있는 재사용 가능한 Roboflow 자격 증명. 다음을 참조하세요. [데이터 소스 자격 증명](/datasets/ko/create-and-upload/adding-data/datasource-credentials.md), 그런 다음 [AWS S3 자격 증명](/datasets/ko/create-and-upload/adding-data/datasource-credentials/aws-s3.md).

### Roboflow에 자격 증명 추가

Roboflow는 버킷 액세스 정보를 안전하게 암호화하여 재사용 가능한 자격 증명으로 저장합니다. AWS 설정 단계와 최소 권한 지침은 [AWS S3 자격 증명](/datasets/ko/create-and-upload/adding-data/datasource-credentials/aws-s3.md).

다음으로 이동하세요 [자격 증명](https://app.roboflow.com/settings/thirdpartykeys) 를 워크스페이스 설정에서 클릭하세요. 그리고 [자격 증명 추가](https://app.roboflow.com/settings/thirdpartykeys#create).

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

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

* "Connection"에는 버킷 세부 정보와 액세스 정보가 들어 있습니다: 이름, 제공업체, 버킷, 리전, 자격 증명. "Credential" 드롭다운에서 저장된 자격 증명을 선택하거나, 양식을 벗어나지 않고 옆의 "+"를 사용해 새로 추가할 수 있습니다.
* "Mirror Configuration"에는 가져오기 대상, 파일 필터, 미러 동작이 들어 있습니다.

### 가져오기 대상 선택

"Mirror Configuration" 아래의 "Import Destination" 섹션에서 미러된 파일이 저장될 위치를 제어합니다. 각 데이터 소스는 하나의 대상에만 가져옵니다. 다른 위치로 가져오려면 데이터 소스를 하나 더 추가하세요.

* "Workspace"는 [자산 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library)자산 라이브러리로 미러링됩니다. "Import into" 드롭다운을 사용해 파일을 워크스페이스 루트에 유지하거나, 프로젝트를 선택해 해당 프로젝트에도 추가하세요.
* "Folder"는 미러된 이미지를 프로젝트 폴더로 범위를 제한하여 해당 폴더의 팀만 볼 수 있게 합니다. 이 옵션은 [프로젝트 폴더 권한](/datasets/ko/manage/project-folders/project-folder-permissions.md).

### 글롭 패턴으로 필터링

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

글롭 패턴 대신 파일 경로의 명시적 화이트리스트를 제공할 수도 있습니다.

### 패턴 의미

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

### 예시

**접두사로 일치:**

```
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` 가 활성화되면 S3 버킷에 더 이상 존재하지 않거나 글롭 패턴과 더 이상 일치하지 않는 파일이, 어떤 프로젝트나 다른 데이터 소스 구성에서도 참조되지 않는 한 Roboflow 작업 공간에서 제거됩니다.

이것은 데이터 소스를 삭제할 때도 적용됩니다. 고아 제거가 활성화되어 있고 버킷이 최소 한 번 이상 미러링되었다면, 다른 프로젝트에서 사용되지 않는 해당 버킷의 이미지는 정리 작업자에 의해 제거될 수 있습니다. 삭제 확인 대화 상자에서 이 점을 경고하며 진행 전에 명시적 확인이 필요합니다. 이를 피하려면 삭제하기 전에 데이터 소스의 미러 구성에서 고아 제거를 비활성화하세요.

### 파일 이름 지정

해당 `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`            |

사이드카 파일 제약 사항:

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

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

이미지의 메타데이터 사이드카 `.json` 파일이 S3에서 업데이트되면, 업데이트가 어떻게 적용될지 제어하는 두 가지 설정이 있습니다:

* `updateMetadataWhenNewer` (기본값: `true`) - 사이드카 파일이 저장된 버전보다 최신이면 메타데이터를 다시 동기화합니다
* `updateMetadataStrategy` - 동기화된 메타데이터가 UI 또는 API를 통해 수동으로 설정한 메타데이터와 어떻게 상호작용할지 제어합니다:

| 전략                      | 동작                                            |
| ----------------------- | --------------------------------------------- |
| `mergeBucketWins` (기본값) | 두 소스를 병합합니다. 키가 충돌하면 버킷 값이 우선합니다              |
| `mergeUserWins`         | 두 소스를 병합합니다. 키가 충돌하면 사용자 설정 값이 우선합니다          |
| `overwrite`             | 버킷 메타데이터가 기존 메타데이터를 완전히 대체합니다                 |
| `untilFirstChange`      | 버킷에서 동기화하다가 사용자가 어떤 메타데이터 필드든 수동으로 편집하면 중지합니다 |
| `append`                | 버킷에서 새로운 키만 추가하고, 기존 키는 절대 덮어쓰지 않습니다          |

## 미러링 트리거하기

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

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

* **진행 중**: 동기화가 이미 실행 중이면 완료될 때까지 다른 동기화를 시작할 수 없습니다.
* **쿨다운**: 동기화가 완료된 후 15분 동안은 수동 재트리거가 차단됩니다. 버튼 툴팁에는 남은 시간이 표시됩니다. 다음 경우 쿨다운이 건너뛰어집니다:
  * 이전 동기화에서 가져올 새 항목이 없었던 경우(큐에 넣은 파일이 0개이거나 모든 파일이 실패한 경우).
  * 마지막 실행 이후 데이터 소스 구성을 수정한 경우.
  * 마지막 실행이 오류와 함께 완료된 경우.
* **시간당 상한**: 데이터 소스는 롤링 1시간 동안 최대 10회만 동기화할 수 있습니다. 이 상한은 쿨다운이 건너뛰어 즉시 재트리거할 수 있는 경우에도 적용됩니다.

예약된(크론) 동기화는 쿨다운과 시간당 상한을 모두 우회합니다.

### 일일 일정으로 실행

자동으로 미러링하려면 "Mirror Configuration" 탭의 "Scheduling" 섹션을 열고 "Run automatically on a daily schedule"를 선택하세요. 그러면 데이터 소스는 24시간마다 동기화됩니다. 스케줄링은 기본적으로 꺼져 있습니다.

## 동기화된 자산 보기

각 [데이터 소스 항목에는](https://app.roboflow.com/settings/datasources) 눈 모양 아이콘이 있으며, 이를 누르면 [자산 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library) 해당 특정 데이터 소스의 이미지와 비디오로 필터링됩니다. 데이터 소스가 최소 한 번의 동기화를 완료하기 전까지는 아이콘이 비활성화됩니다.

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

두 링크 모두 사전 채워진 태그 필터가 적용된 자산 라이브러리로 이동하므로, 작업 공간 이미지 중 버킷 미러링된 부분만 찾아보고, 검색하고, 관리할 수 있습니다.

## S3 호환 스토리지

데이터 소스는 필요한 S3 API 작업을 구현하는 S3 호환 스토리지 제공업체와 함께 작동합니다.

이러한 제공업체 중 하나를 구성하려면:

1. 데이터 소스의 "Connection" 탭에서 `S3` 를 제공업체로 선택하세요.
2. 기존처럼 버킷 이름과 자격 증명을 입력하세요.
3. 제공업체의 사용자 지정 `엔드포인트` URL.
4. 를 `auto` 또는 해당 제공업체 고유의 리전 값으로 설정하세요.

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

동일한 글롭 패턴 필터링, 메타데이터 사이드카 동작, 미러 설정도 이러한 제공업체와 함께 작동합니다.

지원되는 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 호스티드 S3 게이트웨이                               | `gateway.storjshare.io`                            |