> 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/roboflow/roboflow-ko/datasets/adding-data/datasources.md). # Datasources Datasources를 사용하면 cloud storage의 이미지와 metadata를 Roboflow asset library에 지속적으로 미러링할 수 있습니다. 미러링된 이미지는 의미론, custom metadata, 태그 또는 이미지 유사도로 검색할 수 있으며, labeling 및 training을 위해 모든 Project에 추가할 수 있습니다. 현재 AWS S3 및 S3-compatible storage bucket 미러링이 지원됩니다. Azure Blob Storage 및 Google Cloud Storage 지원은 곧 제공될 예정입니다. {% hint style="warning" %} 소스 데이터가 AWS S3와 같은 cloud storage에 있는 경우, Roboflow로 가져오는 기본 경로로 Datasources 및 Bucket Mirror를 사용하세요. 일회성 또는 임시 import에만 signed URL upload 또는 local download workflow를 사용하세요. {% endhint %} ## Bucket Mirror 작동 방식 Datasource를 구성하면 Roboflow가 S3 bucket을 크롤링하고 일치하는 모든 이미지 파일을 Workspace의 [Asset Library](/roboflow/roboflow-ko/workspaces/asset-library.md). * 지원되는 이미지 형식: JPEG, PNG, BMP, WebP, AVIF * Workspace에 이미 있는 파일(S3 위치 및 hash로 일치)은 다시 import되지 않으므로 egress 비용이 줄어듭니다. * 만약 `.json` 동일한 base name의 이미지와 함께 sidecar 파일이 존재하면 해당 metadata를 import합니다. 중첩 키는 dot notation을 사용하여 평면화됩니다(예: `capture.temperature`) — 참조: [Metadata Sidecars](#metadata-sidecars) * Bucket에서 사라진 파일은 기본적으로 유지됩니다. 대신 삭제하려면 orphan removal을 활성화하세요(참조: [Removing Orphaned Files](#removing-orphaned-files)) ## Bucket을 Roboflow로 미러링하기 ### 사전 요구 사항 1. 이미지 데이터가 포함된 AWS S3 bucket 2. 해당 bucket에서 읽을 수 있는 재사용 가능한 Roboflow credential입니다. 참조: [Datasource Credentials](/roboflow/roboflow-ko/datasets/adding-data/datasources/datasource-credentials.md), 그다음 [AWS S3 Credentials](/roboflow/roboflow-ko/datasets/adding-data/datasources/datasource-credentials/aws-s3.md). ### Roboflow에서 Credential 추가 Roboflow는 bucket access를 재사용 가능한 credential로 안전하게 암호화하여 저장합니다. AWS 설정 단계 및 least-privilege 지침은 다음을 사용하세요. [AWS S3 Credentials](/roboflow/roboflow-ko/datasets/adding-data/datasources/datasource-credentials/aws-s3.md). 이동: [Credentials](https://app.roboflow.com/settings/thirdpartykeys) Workspace settings에서 을(를) 열고 [Add Credential](https://app.roboflow.com/settings/thirdpartykeys#create). ### Bucket Mirroring용 Datasource 구성 [새 Datasource 생성](https://app.roboflow.com/settings/datasources) Workspace settings에서 생성합니다. 양식에는 두 개의 탭이 있습니다: * "Connection"에는 이름, provider, bucket, region 및 Credential 등 bucket 세부 정보와 access 정보가 있습니다. "Credential" dropdown에서 저장된 Credential을 선택하거나, 옆의 "+"를 사용하여 양식을 벗어나지 않고 추가하세요. * "Mirror Configuration"에는 import destination, file filter 및 mirror behavior가 있습니다. ### Import Destination 선택 "Mirror Configuration" 아래의 "Import Destination" 섹션은 미러링된 파일이 저장되는 위치를 제어합니다. 각 Datasource는 단일 destination으로 import합니다. 다른 위치로 import하려면 다른 Datasource를 추가하세요. * "Workspace"는 다음으로 미러링합니다: [Asset Library](/roboflow/roboflow-ko/workspaces/asset-library.md). "Import into" dropdown을 사용하여 파일을 Workspace root에 유지하거나, Project를 선택하여 해당 Project에도 추가하세요. * "Folder"는 미러링된 이미지를 project folder로 제한하여 해당 folder의 team만 볼 수 있게 합니다. 이 옵션은 다음이 포함된 plan에서 사용할 수 있습니다. [Project Folder Permissions](/roboflow/roboflow-ko/datasets/project-folders/project-folder-permissions.md). ### Glob Pattern으로 필터링 기본적으로 bucket의 지원되는 모든 이미지 파일을 import합니다. 직접 지정하거나 다음을 통해 glob pattern을 사용하여 import할 파일을 제한할 수 있습니다. `.txt` bucket에 저장된 파일입니다. glob pattern 대신 파일 path의 명시적 whitelist를 제공할 수도 있습니다. ### Pattern semantics * `*` 다음을 제외한 모든 문자와 일치 `/` (단일 directory level) * `**` 다음을 포함한 모든 문자와 일치 `/` (여러 directory level) ### 예시 **Prefix로 일치:** ``` harvest** ``` 일치 항목: `harvest`, `harvest2024`, `harvest/sun/file.jpg`, `harvest-data.png`\ 일치하지 않는 항목: `Harvest`, `my-harvest` **Folder 내 모든 항목 일치:** ``` /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` **Subtree 내 suffix로 일치:** ``` /planting/**/*crops.png ``` 일치 항목: `/planting/wheat-crops.png`, `/planting/subfolder/rice-crops.png`\ 일치하지 않는 항목: `/planting/wheat.png`, `/other/wheat-crops.png` **이름 pattern을 사용하여 특정 directory level에서 일치:** ``` /*/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` **정확한 path:** ``` /exact/path/to/file.jpg ``` 해당 특정 파일에만 일치합니다. **Filename의 literal wildcard:**\ 다음을 literal character로 처리하려면 pattern을 따옴표로 감싸세요: `*` 을(를) literal character로 처리: ``` "/path/to/file*.jpg" ``` ### Removing Orphaned Files Orphan removal은 기본적으로 꺼져 있으므로 bucket에서 사라진 파일은 유지됩니다. `removeOrphanedSourcesWhenDisappeared` 가 활성화되면, 더 이상 S3 bucket에 없거나 glob pattern과 더 이상 일치하지 않는 파일은 어떤 Project 또는 다른 Datasource configuration에서도 참조되지 않는 경우 Roboflow Workspace에서 제거됩니다. 이는 Datasource를 삭제할 때도 적용됩니다. Orphan removal이 활성화되어 있고 bucket이 한 번 이상 미러링된 경우, 다른 Project에서 사용되지 않는 해당 bucket 원본 이미지는 cleanup worker에 의해 제거될 수 있습니다. 삭제 확인 dialog에서 이에 대해 경고하고 진행 전 명시적 확인을 요구합니다. 이를 방지하려면 Datasource를 삭제하기 전에 해당 Datasource의 mirror configs에서 orphan removal을 비활성화하세요. ### 파일 이름 지정 다음 `namingStrategy` 설정은 import된 파일의 이름 지정 및 Roboflow 내 표시 방식을 제어합니다: | 전략 | 설명 | | ---------- | ------------------------------------------------------------------- | | `fullPath` | 전체 S3 key path를 filename으로 사용합니다(기본값). | | `fileName` | S3 key의 filename 부분만 사용합니다. | | `eTag` | S3 object ETag를 사용합니다. | | `metadata` | 이미지 metadata의 값을 사용하며, 다음으로 지정됩니다: `namingStrategyMetadataKey` (필수) | ### 이미지 업데이트 S3의 이미지가 수정되면 Roboflow가 Workspace의 사본을 업데이트할 수 있습니다: * `updateImageWhenNewer` (기본값: `true`) — S3 object가 저장된 버전보다 최신이면 이미지를 다시 import합니다. * `updateImageStrategy` — 업데이트 적용 방식을 제어합니다. 현재 `overwrite` (기존 이미지를 대체)가 지원됩니다. ### Metadata Sidecars 다음을 배치하여 이미지에 metadata를 첨부합니다: `.json` 각 이미지와 동일한 base name을 사용하는 sidecar 파일을 bucket에 함께 배치합니다: ``` my-bucket/ images/ photo_001.jpg photo_001.json # photo_001.jpg의 metadata photo_002.jpg photo_002.json # photo_002.jpg의 metadata ``` Sidecar 파일에는 key-value pair가 포함됩니다: ```json { "camera_id": "cam001", "location": "warehouse-3", "capture": { "temperature": 72.5, "humidity": 45 } } ``` 중첩 object는 dot notation을 사용하여 평면화됩니다. 위 예시는 다음을 생성합니다: | 키 | 값 | | --------------------- | --------------- | | `camera_id` | `"cam001"` | | `location` | `"warehouse-3"` | | `capture.temperature` | `72.5` | | `capture.humidity` | `45` | Sidecar 파일 제약 사항: * 최대 파일 크기: 256KB * 유효한 JSON이어야 함 * `null` 및 `undefined` 값은 필터링되어 제외됩니다. ### Metadata Sync 전략 이미지의 metadata sidecar `.json` 파일이 S3에서 업데이트되면 두 설정이 업데이트 적용 방식을 제어합니다: * `updateMetadataWhenNewer` (기본값: `true`) — sidecar 파일이 저장된 버전보다 최신이면 metadata를 다시 sync합니다. * `updateMetadataStrategy` — sync된 metadata가 UI 또는 API를 통해 수동으로 설정한 metadata와 상호작용하는 방식을 제어합니다: | 전략 | 동작 | | ----------------------- | --------------------------------------------------------- | | `mergeBucketWins` (기본값) | 두 source를 병합하며, key 충돌 시 bucket 값이 우선합니다. | | `mergeUserWins` | 두 source를 병합하며, key 충돌 시 사용자가 설정한 값이 우선합니다. | | `overwrite` | Bucket metadata가 기존의 모든 metadata를 완전히 대체합니다. | | `untilFirstChange` | 사용자가 metadata field를 수동으로 편집할 때까지 bucket에서 sync한 후 중지합니다. | | `append` | Bucket에서 새 key만 추가하며 기존 key는 절대 덮어쓰지 않습니다. | ## 미러링 트리거 다음에서 언제든지 수동으로 mirror를 트리거할 수 있습니다: [Datasources 목록](https://app.roboflow.com/settings/datasources) 에서 Datasource 옆의 play button을 클릭합니다. 수동 트리거에는 다음 보호 장치가 적용됩니다: * **진행 중**: 이미 sync가 실행 중이면 완료될 때까지 다른 sync를 시작할 수 없습니다. * **Cooldown**: Sync가 완료된 후 수동 재트리거는 15분 동안 차단됩니다. Button tooltip에 남은 시간이 표시됩니다. 다음 경우에는 cooldown이 건너뛰어집니다: * 이전 sync에서 import할 새 항목을 찾지 못한 경우(큐에 추가된 파일이 0개이거나 모든 파일이 실패한 경우). * 마지막 실행 이후 Datasource configuration을 편집한 경우. * 마지막 실행이 오류와 함께 완료된 경우. * **시간당 상한**: Datasource는 rolling hour당 최대 10회 sync할 수 있습니다. Cooldown skip으로 즉시 재트리거가 허용되는 경우에도 이 상한은 적용됩니다. Scheduled (cron) sync는 cooldown과 시간당 상한을 모두 우회합니다. ### 매일 일정에 따라 실행 자동으로 미러링하려면 "Mirror Configuration" 탭 아래의 "Scheduling" 섹션을 열고 "Run automatically on a daily schedule"을 선택하세요. 그러면 Datasource는 24시간마다 sync됩니다. Scheduling은 기본적으로 꺼져 있습니다. ## Sync된 Asset 보기 각 [datasource 항목](https://app.roboflow.com/settings/datasources) 에는 다음을 여는 eye icon이 있습니다: [Asset Library](/roboflow/roboflow-ko/workspaces/asset-library.md) 해당 특정 Datasource의 이미지 및 비디오로 필터링됩니다. Datasource가 최소 한 번의 sync를 완료할 때까지 icon은 비활성화됩니다. 모든 Datasource에서 sync된 모든 이미지를 보려면 Datasources 목록 하단의 "View Datasource Assets"를 클릭하세요. 이 link는 최소 하나의 Datasource가 실행된 후 표시됩니다. 두 link 모두 미리 채워진 tag filter가 적용된 Asset Library로 이동하므로 Workspace 이미지 중 bucket-mirrored subset만 탐색, 검색 및 관리할 수 있습니다. ## S3-compatible storage Datasources는 필수 S3 API operation을 구현하는 S3-compatible storage provider와 함께 작동합니다. 이러한 provider 중 하나를 구성하려면: 1. Datasource "Connection" 탭에서 다음을 선택합니다: `S3` 를 provider로 선택합니다. 2. 평소와 같이 bucket name과 credentials를 입력합니다. 3. Provider의 custom `endpoint` URL을 정의합니다. 4. Region을 다음으로 설정합니다: `auto` 또는 provider별 region 값. 다음에 provider의 S3 API endpoint를 사용하세요: `endpoint`. CDN URL, public bucket URL 또는 browser download URL은 사용하지 마세요. 동일한 glob pattern filtering, metadata sidecar behavior 및 mirror settings가 이러한 provider에서도 작동합니다. 지원되는 S3-compatible storage provider는 다음과 같습니다: | Provider | 예시 endpoint hostname | | ----------------------------------------------------------- | -------------------------------------------------- | | 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` |