> 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로 가져오고, 수집하고, 동기화하는 기본 경로로 Datasources와 Bucket Mirror를 사용하세요. 서명된 URL 업로드나 로컬 다운로드 워크플로는 일회성 또는 임시 가져오기에만 사용하세요. {% endhint %} ## Bucket Mirror 작동 방식 Datasource를 구성하면 Roboflow가 버킷을 크롤링하여 일치하는 모든 이미지 파일을 워크스페이스의 [자산 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library). * 지원되는 이미지 형식: JPEG, PNG, BMP, WebP, AVIF * 이미 워크스페이스에 있는 파일은(버킷 위치와 해시로 일치하는 경우) 다시 가져오지 않아 egress 비용을 줄입니다 * 만약 `.json` 사이드카 파일이 같은 기본 이름의 이미지와 함께 존재하면 해당 메타데이터가 가져와집니다. 중첩 키는 점 표기법을 사용해 평탄화됩니다(예: `capture.temperature`) - [메타데이터 사이드카](#metadata-sidecars) * 버킷에서 사라진 파일은 기본적으로 유지됩니다. 대신 삭제하려면 고아 항목 제거를 활성화하세요(참조: [고아 파일 제거](#removing-orphaned-files)) ### 동영상 Roboflow는 최대 3 GB까지의 MP4 및 QuickTime(`.mov`) 동영상도 미러링합니다. 동영상은 자산 라이브러리에만 저장되며 프로젝트에 추가되지 않고, 프레임도 추출되지 않습니다. 동영상은 이미지와 마찬가지로 `.json` 사이드카 메타데이터를 읽습니다. 동영상을 제외하려면 이미지 파일만 일치하는 glob 패턴을 사용하세요. ## 버킷을 Roboflow로 미러링하기 ### 사전 요구 사항 1. 이미지 데이터를 포함한 클라우드 스토리지 버킷(AWS S3, Google Cloud Storage 또는 Azure Blob Storage) 2. 해당 버킷에서 읽을 수 있는 재사용 가능한 Roboflow 자격 증명. 참조: [Datasource 자격 증명](/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), 또는 [Azure Blob Storage 자격 증명](/datasets/ko/create-and-upload/adding-data/datasource-credentials/azure.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), 또는 [Azure Blob Storage 자격 증명](/datasets/ko/create-and-upload/adding-data/datasource-credentials/azure.md). 이동: [자격 증명](https://app.roboflow.com/settings/thirdpartykeys) 을 워크스페이스 설정에서 선택한 다음 [자격 증명 추가](https://app.roboflow.com/settings/thirdpartykeys#create). ### 버킷 미러링용 Datasource 구성 [새 Datasource 만들기](https://app.roboflow.com/settings/datasources) 를 워크스페이스 설정에서 만드세요. 양식에는 두 개의 탭이 있습니다: * "Connection"에는 버킷 세부 정보와 접근 정보가 들어 있습니다: 이름, 공급자, 버킷, 리전, 자격 증명. 저장된 자격 증명을 "Credential" 드롭다운에서 선택하거나, 양식을 떠나지 않고 오른쪽의 "+"를 사용해 추가할 수 있습니다. * "Mirror Configuration"에는 가져오기 대상, 파일 필터, 미러 동작이 들어 있습니다. "Bucket" 필드는 버킷 이름만 입력받습니다(예: `my-bucket`, `s3://my-bucket`). 이름 뒤에 경로가 포함된 버킷 값은 거부됩니다. 버킷의 일부만 미러링하려면 "Mirror Configuration" 탭의 "File Filters" 아래에 `images/**/*` 와 같은 glob 패턴을 추가하세요. Azure Blob Storage의 경우에도 동일한 규칙이 컨테이너 이름에 적용됩니다. ### 가져오기 대상 선택 "Mirror Configuration" 아래의 "Import Destination" 섹션은 미러링된 파일이 어디에 저장될지 제어합니다. 각 Datasource는 하나의 대상만 가져올 수 있으며, 다른 곳으로 가져오려면 Datasource를 하나 더 추가하세요. * "Workspace"는 미러링을 [자산 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library)로 보냅니다. 파일을 워크스페이스 루트에 유지하려면 "Import into" 드롭다운을 사용하고, 특정 프로젝트에 추가하려면 프로젝트를 선택하세요. * "Folder"는 미러링된 이미지를 프로젝트 폴더로 범위를 제한하여 해당 폴더의 팀만 볼 수 있게 합니다. 이 옵션은 다음이 포함된 요금제에서 사용할 수 있습니다. [프로젝트 폴더 권한](/datasets/ko/manage/project-folders/project-folder-permissions.md). ### Glob 패턴으로 필터링 기본적으로 버킷의 모든 지원 이미지 파일이 가져와집니다. 직접 지정하거나 `.txt` 파일을 통해 glob 패턴을 사용해 가져올 파일을 제한할 수 있습니다. 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` 가 활성화되면, 버킷에 더 이상 존재하지 않거나 glob 패턴에 더 이상 일치하지 않는 파일은 Roboflow 워크스페이스에서 제거됩니다. 단, 어떤 프로젝트나 다른 Datasource 구성에서도 참조되지 않아야 합니다. 이 설정은 Datasource를 삭제할 때도 적용됩니다. 고아 항목 제거가 활성화되어 있고 버킷이 최소 한 번 이상 미러링된 경우, 다른 프로젝트에서 사용되지 않는 해당 버킷의 이미지는 정리 작업자가 제거할 수 있습니다. 삭제 확인 대화상자는 이를 경고하고 진행 전에 명시적 확인을 요구합니다. 이를 피하려면 삭제하기 전에 Datasource의 미러 구성에서 고아 항목 제거를 비활성화하세요. ### 파일 이름 지정 이 `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` | 버킷에서 새 키만 추가하며 기존 키는 절대 덮어쓰지 않습니다 | ## 미러링 트리거하기 다음에서 언제든지 수동으로 미러를 트리거할 수 있습니다 [Datasources 목록](https://app.roboflow.com/settings/datasources) Datasource 옆의 재생 버튼을 클릭하여. 수동 트리거에는 다음 보호 장치가 적용됩니다: * **실행 중**: 이미 동기화가 실행 중이면, 완료될 때까지 다른 동기화를 시작할 수 없습니다. * **쿨다운**: 동기화가 완료되면 15분 동안 수동 재트리거가 차단됩니다. 버튼 툴팁에는 남은 분 수가 표시됩니다. 다음 경우에는 쿨다운이 건너뜁니다: * 이전 동기화에서 가져올 새 항목이 없었습니다(대기열에 들어간 파일이 0개이거나, 모든 파일이 실패함). * 마지막 실행 이후 Datasource 구성을 수정했습니다. * 마지막 실행이 오류와 함께 완료되었습니다. * **시간당 상한**: Datasource는 롤링 1시간당 최대 10회만 동기화할 수 있습니다. 이 상한은 쿨다운 건너뛰기로 즉시 재트리거할 수 있는 경우에도 적용됩니다. 예약된(cron) 동기화는 쿨다운과 시간당 상한을 모두 우회합니다. ### 일일 일정으로 실행 자동으로 미러링하려면 "Mirror Configuration" 탭의 "Scheduling" 섹션을 열고 "Run automatically on a daily schedule"을 선택하세요. 그러면 datasource가 24시간마다 동기화됩니다. 일정 설정은 기본적으로 꺼져 있습니다. ## 동기화된 자산 보기 각각의 [datasource 항목은](https://app.roboflow.com/settings/datasources) 눈 아이콘이 있으며 이를 열면 [자산 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library) 해당 특정 Datasource의 이미지와 동영상으로 필터링됩니다. Datasource가 최소 한 번의 동기화를 완료하기 전까지는 아이콘이 비활성화됩니다. 어떤 Datasource에서든 동기화된 모든 이미지를 보려면 Datasources 목록 하단의 "View Datasource Assets"를 클릭하세요. 이 링크는 최소 한 번의 Datasource가 실행된 후 나타납니다. 두 링크 모두 미리 채워진 태그 필터가 있는 자산 라이브러리로 이동하므로, 워크스페이스 이미지 중 버킷 미러링된 하위 집합만 찾아보고, 검색하고, 관리할 수 있습니다. ## S3 호환 스토리지 Datasources는 필요한 S3 API 작업을 구현한 S3 호환 스토리지 공급자와 함께 작동합니다. 이들 공급자 중 하나를 구성하려면: 1. Datasource의 "Connection" 탭에서 `S3` 를 공급자로 선택하세요. 2. 버킷 이름과 자격 증명을 평소처럼 입력하세요. 3. 공급자의 사용자 정의 `엔드포인트` URL을 정의하세요. 4. 리전을 다음으로 설정하세요 `auto` 또는 공급자별 리전 값으로 설정하세요. 공급자의 S3 API 엔드포인트를 `엔드포인트`에 사용하세요. CDN URL, 공개 버킷 URL 또는 브라우저 다운로드 URL은 사용하지 마세요. 엔드포인트는 공개 인터넷에서 접근 가능해야 합니다. Roboflow는 다음을 가리키는 엔드포인트를 거부합니다 `localhost`, 비공개 네트워크 주소 또는 링크 로컬 주소를 가리키는 엔드포인트도 거부하며, 그런 주소로 해석되는 호스트 이름도 거부합니다. 동일한 glob 패턴 필터링, 메타데이터 사이드카 동작, 미러 설정도 이러한 공급자와 함께 작동합니다. ### 경로 스타일 주소 지정 일부 공급자는 URL 경로에 버킷 이름을 기대합니다(`endpoint/bucket/key`) 호스트 이름이 아니라(`bucket.endpoint/key`). 엔드포인트를 입력하면 "Connection" 탭에 "Use path-style addressing" 체크박스가 나타납니다. Roboflow는 엔드포인트와 일치하는 설정을 미리 선택하며, 사용자가 변경해도 선택을 유지합니다. MinIO 및 기타 자체 호스팅 또는 NAS 게이트웨이, Oracle Cloud 호환성 엔드포인트, IP 주소나 포트로 접근하는 모든 엔드포인트, 이름에 점이 있는 버킷에는 이 옵션을 켜세요. 가상 호스티드 URL을 제공하는 공급자(예: Cloudflare R2, Backblaze B2, Wasabi, DigitalOcean Spaces, Alibaba Cloud OSS)에는 끄세요. 잘못된 설정을 사용하면 파일을 나열할 때 연결 테스트가 실패하며, 오류 메시지에서 전환하라고 알려줍니다. 지원되는 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 호환 | `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를 만듭니다.
datasource_validateRoboflow가 버킷에 도달할 수 있는지 확인합니다.
datasource_trigger미러 실행을 시작합니다.
datasource_job_get하나의 미러 실행 상태와 통계를 가져옵니다.