> 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 호환 스토리지, Google Cloud Storage, Azure Blob Storage 버킷 미러링이 지원됩니다. {% hint style="warning" %} 원본 데이터가 AWS S3, Google Cloud Storage, Azure Blob Storage와 같은 클라우드 스토리지에 있는 경우, 데이터를 Roboflow로 가져오고 수집하며 동기화하는 기본 경로로 Datasources와 Bucket Mirror를 사용하세요. 서명된 URL 업로드나 로컬 다운로드 워크플로는 일회성 또는 임시 가져오기에만 사용하세요. {% endhint %} ## 버킷 미러 작동 방식 데이터소스를 구성하면 Roboflow가 버킷을 크롤링하여 일치하는 모든 이미지 파일을 워크스페이스의 [에셋 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library). * 지원되는 이미지 형식: JPEG, PNG, BMP, WebP, AVIF * 이미 워크스페이스에 있는 파일(버킷 위치와 해시가 일치하는 파일)은 다시 가져오지 않으므로 egress 비용이 줄어듭니다 * 만약 `.json` 같은 기본 이름을 가진 이미지 옆에 sidecar 파일이 있으면 해당 메타데이터가 가져와집니다. 중첩된 키는 점 표기법으로 평탄화됩니다(예: `capture.temperature`) - 자세한 내용은 [메타데이터 사이드카](#metadata-sidecars) * 버킷에서 사라진 파일은 기본적으로 유지됩니다. 대신 고아 제거를 활성화하여 삭제할 수 있습니다(자세한 내용은 [고아 파일 제거](#removing-orphaned-files)) ## 버킷을 Roboflow에 미러링하기 ### 사전 요구 사항 1. 이미지 데이터가 들어 있는 클라우드 스토리지 버킷(AWS S3, Google Cloud Storage 또는 Azure Blob Storage) 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) 또는 [Google Cloud Storage 자격 증명](/datasets/ko/create-and-upload/adding-data/datasource-credentials/gcs.md). ### Roboflow에서 자격 증명 추가하기 Roboflow는 버킷 접근 권한을 재사용 가능한 자격 증명으로 안전하게 암호화하여 저장합니다. 공급자별 설정 단계와 최소 권한 가이드는 [AWS S3 자격 증명](/datasets/ko/create-and-upload/adding-data/datasource-credentials/aws-s3.md) 또는 [Google Cloud Storage 자격 증명](/datasets/ko/create-and-upload/adding-data/datasource-credentials/gcs.md). 로 이동하여 [자격 증명](https://app.roboflow.com/settings/thirdpartykeys) 을 워크스페이스 설정에서 클릭한 다음 [자격 증명 추가](https://app.roboflow.com/settings/thirdpartykeys#create). ### 버킷 미러링을 위한 데이터소스 구성 [새 데이터소스 만들기](https://app.roboflow.com/settings/datasources) 를 워크스페이스 설정에서 생성하세요. 양식에는 두 개의 탭이 있습니다: * "연결"에는 버킷 세부 정보와 접근 정보가 들어 있습니다: 이름, 공급자, 버킷, 리전, 자격 증명. "자격 증명" 드롭다운에서 저장한 자격 증명을 선택하거나, 양식을 벗어나지 않고 옆의 "+"를 사용해 추가할 수 있습니다. * "미러 구성"에는 가져오기 대상, 파일 필터, 미러 동작이 들어 있습니다. ### 가져오기 대상 선택 "미러 구성" 아래의 "가져오기 대상" 섹션은 미러링된 파일이 어디로 들어갈지를 제어합니다. 각 데이터소스는 하나의 대상에만 가져올 수 있으며, 다른 곳에 가져오려면 데이터소스를 하나 더 추가하세요. * "워크스페이스"는 다음으로 미러링합니다. [에셋 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library). "가져오기 위치" 드롭다운을 사용해 파일을 워크스페이스 루트에 둘지, 또는 프로젝트를 선택해 해당 프로젝트에도 추가할지 정할 수 있습니다. * "폴더"는 미러링된 이미지를 프로젝트 폴더로 범위를 제한하여, 그 폴더의 팀만 볼 수 있게 합니다. 이 옵션은 다음이 포함된 요금제에서 사용할 수 있습니다. [프로젝트 폴더 권한](/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` 가 활성화되면, 더 이상 버킷에 없거나 더 이상 글롭 패턴과 일치하지 않는 파일은 다른 프로젝트나 다른 데이터소스 구성에서 참조되지 않는 한 Roboflow 워크스페이스에서 제거됩니다. 이것은 데이터소스를 삭제할 때도 적용됩니다. 고아 제거가 활성화되어 있고 버킷이 최소 한 번은 미러링되었다면, 다른 어떤 프로젝트에서도 사용되지 않는 해당 버킷의 이미지가 정리 작업자에 의해 제거될 수 있습니다. 삭제 확인 대화상자는 이를 경고하고 진행하기 전에 명시적 확인을 요구합니다. 이를 피하려면 삭제하기 전에 데이터소스의 미러 구성에서 고아 제거를 비활성화하세요. ### 파일 이름 지정 다음 `namingStrategy` 설정은 Roboflow에서 가져온 파일의 이름과 표시 방식을 제어합니다: | 전략 | 설명 | | ---------- | ---------------------------------------------------------------- | | `fullPath` | 전체 S3 키 경로를 파일명으로 사용합니다(기본값) | | `fileName` | S3 키의 파일명 부분만 사용합니다 | | `eTag` | S3 오브젝트 ETag를 사용합니다 | | `메타데이터` | 이미지 메타데이터의 값을 사용합니다. 다음으로 지정합니다 `namingStrategyMetadataKey` (필수) | ### 이미지 업데이트 S3의 이미지가 수정되면 Roboflow가 워크스페이스의 복사본을 업데이트할 수 있습니다: * `updateImageWhenNewer` (기본값: `true`) - 저장된 버전보다 S3 오브젝트가 더 최신이면 이미지를 다시 가져옵니다 * `updateImageStrategy` - 업데이트가 적용되는 방식을 제어합니다. 현재는 `overwrite` (기존 이미지를 대체함)만 지원됩니다 ### 메타데이터 사이드카 각 이미지 옆에 버킷 안에 `.json` sidecar 파일을 두어 이미지를 메타데이터와 함께 연결합니다. 같은 기본 이름을 사용하세요: ``` my-bucket/ images/ photo_001.jpg photo_001.json # photo_001.jpg의 메타데이터 photo_002.jpg photo_002.json # photo_002.jpg의 메타데이터 ``` sidecar 파일에는 키-값 쌍이 들어 있습니다: ```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` | sidecar 파일 제약 조건: * 최대 파일 크기: 256 KB * 유효한 JSON이어야 함 * `null` 와 `undefined` 값은 필터링됩니다 ### 메타데이터 동기화 전략 이미지의 메타데이터 sidecar `.json` 파일이 S3에서 업데이트되면, 두 가지 설정이 업데이트 적용 방식을 제어합니다: * `updateMetadataWhenNewer` (기본값: `true`) - sidecar 파일이 저장된 버전보다 더 최신이면 메타데이터를 다시 동기화합니다 * `updateMetadataStrategy` - 동기화된 메타데이터가 UI나 API를 통해 수동으로 설정한 메타데이터와 어떻게 상호작용할지 제어합니다: | 전략 | 동작 | | ----------------------- | ----------------------------------------------------- | | `mergeBucketWins` (기본값) | 두 소스를 병합합니다. 키 충돌 시 버킷 값이 우선합니다 | | `mergeUserWins` | 두 소스를 병합합니다. 키 충돌 시 사용자가 설정한 값이 우선합니다 | | `overwrite` | 버킷 메타데이터가 기존 메타데이터 전체를 완전히 대체합니다 | | `untilFirstChange` | 사용자가 메타데이터 필드를 수동으로 편집할 때까지 버킷에서 동기화한 뒤, 그 이후에는 중지합니다 | | `append` | 버킷에서 새 키만 추가하고 기존 키는 절대 덮어쓰지 않습니다 | ## 미러링 트리거하기 다음에서 언제든지 수동으로 미러를 트리거할 수 있습니다 [데이터소스 목록](https://app.roboflow.com/settings/datasources) 에서 데이터소스 옆의 재생 버튼을 클릭하여. 수동 트리거에는 다음 보호 장치가 적용됩니다: * **진행 중**: 이미 동기화가 실행 중이면, 완료될 때까지 다른 동기화를 시작할 수 없습니다. * **쿨다운**: 동기화가 완료된 후에는 15분 동안 수동 재트리거가 차단됩니다. 버튼 툴팁에 남은 분이 표시됩니다. 다음 경우에는 쿨다운이 건너뛰어집니다: * 이전 동기화에서 새로 가져올 항목이 없었습니다(대기열에 들어간 파일이 0개이거나 모든 파일이 실패함). * 마지막 실행 이후 데이터소스 구성을 편집했습니다. * 마지막 실행이 오류와 함께 완료되었습니다. * **시간당 상한**: 데이터소스는 진행 중인 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. 공급자의 사용자 지정 `엔드포인트` URL을 정의하세요. 4. 리전을 `auto` 또는 공급자별 리전 값으로 설정하세요. 공급자의 S3 API 엔드포인트를 `엔드포인트`에 사용하세요. CDN URL, 공개 버킷 URL 또는 브라우저 다운로드 URL은 사용하지 마세요. 같은 글롭 패턴 필터링, 메타데이터 sidecar 동작, 미러 설정도 이러한 공급자에서 작동합니다. ### 경로 스타일 주소 지정 일부 공급자는 버킷 이름이 호스트명이 아니라 URL 경로에 들어가길 기대합니다(`endpoint/bucket/key`) (`bucket.endpoint/key`). 엔드포인트를 입력하면 "연결" 탭에 "경로 스타일 주소 지정 사용" 체크박스가 나타납니다. Roboflow는 엔드포인트와 일치하는 설정을 미리 선택하고, 이를 변경해도 선택을 유지합니다. MinIO 및 기타 자체 호스팅 또는 NAS 게이트웨이, Oracle Cloud 호환 엔드포인트, IP 주소나 포트로 접근하는 모든 엔드포인트, 이름에 점이 있는 버킷에는 이를 켜세요. Cloudflare R2, Backblaze B2, Wasabi, DigitalOcean Spaces, Alibaba Cloud OSS처럼 가상 호스팅 URL을 제공하는 공급자에는 끄세요. 잘못된 설정을 사용하면 연결 테스트가 파일을 나열할 때 실패하며, 오류 메시지에서 변경하라고 안내합니다. 지원되는 S3 호환 스토리지 공급자는 다음과 같습니다: | 공급자 | 예시 엔드포인트 호스트명 | | ----------------------------------------------------------- | -------------------------------------------------- | | Cloudflare R2 | `.r2.cloudflarestorage.com` | | Backblaze B2 | `s3..backblazeb2.com` | | DigitalOcean Spaces | `.digitaloceanspaces.com` | | Akamai Linode Object Storage | `.linodeobjects.com` | | Wasabi | `s3..wasabisys.com` | | Vultr Object Storage | `.vultrobjects.com` | | OVHcloud Object Storage | `s3..io.cloud.ovh.net` | | Scaleway Object Storage | `s3..scw.cloud` | | Open Telekom Cloud | `obs..otc.t-systems.com` | | Exoscale SOS | `sos-.exo.io` | | IONOS Cloud Object Storage | `s3-.ionoscloud.com` | | IBM Cloud Object Storage | `s3..cloud-object-storage.appdomain.cloud` | | Oracle Cloud Infrastructure Object Storage S3 Compatibility | `compat.objectstorage..oraclecloud.com` | | Seagate Lyve Cloud | `s3..lyvecloud.seagate.com` | | Huawei Cloud OBS | `obs..myhuaweicloud.com` | | Alibaba Cloud OSS | `oss-.aliyuncs.com` | | Tencent Cloud COS | `cos..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) 그리고 다음 도구로 버킷을 프로젝트에 미러링할 수 있습니다:
도구설명
connect_cloud_storage자격 증명부터 첫 실행까지, 버킷 미러를 처음부터 끝까지 설정합니다.
credentials_create클라우드 스토리지 자격 증명을 만듭니다.
credentials_list워크스페이스의 클라우드 스토리지 자격 증명을 나열합니다.
datasource_create버킷 경로를 프로젝트에 미러링하는 데이터소스를 만듭니다.
datasource_validateRoboflow가 버킷에 접근할 수 있는지 확인합니다.
datasource_trigger미러 실행을 시작합니다.
datasource_job_get하나의 미러 실행의 상태와 통계를 가져옵니다.