> 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/ja/toappurdo/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によるアップロードやローカルへのダウンロードを使った方法は、1回限りまたは臨時のインポートに限って使用してください。
{% 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`）形式の動画も、それぞれ最大3 GBまでミラーリングします。動画はアセットライブラリにのみ保存され、プロジェクトには追加されず、フレームも抽出されません。動画でも画像と同じ方法で `.json` サイドカーのメタデータが読み込まれます。動画を除外するには、画像ファイルだけに一致するglobパターンを使用してください。

## バケットをRoboflowにミラーリングする

### 前提条件

1. 画像データを含むクラウドストレージのバケット（AWS S3、Google Cloud Storage、Azure Blob Storage）
2. そのバケットを読み取れる、再利用可能なRoboflow認証情報。詳しくは [データソースの認証情報](https://docs.roboflow.com/datasets/ja/toappurdo/adding-data/datasource-credentials.md)を参照し、次の該当する手順に従ってください： [AWS S3の認証情報](https://docs.roboflow.com/datasets/ja/toappurdo/adding-data/datasource-credentials/aws-s3.md), [Google Cloud Storageの認証情報](https://docs.roboflow.com/datasets/ja/toappurdo/adding-data/datasource-credentials/gcs.md)または [Azure Blob Storageの認証情報](https://docs.roboflow.com/datasets/ja/toappurdo/adding-data/datasource-credentials/azure.md).

### Roboflowで認証情報を追加する

Roboflowはバケットへのアクセス情報を安全に暗号化して保存し、再利用可能な認証情報として管理します。プロバイダーごとの設定手順と最小権限に関するガイダンスは、次を参照してください： [AWS S3の認証情報](https://docs.roboflow.com/datasets/ja/toappurdo/adding-data/datasource-credentials/aws-s3.md), [Google Cloud Storageの認証情報](https://docs.roboflow.com/datasets/ja/toappurdo/adding-data/datasource-credentials/gcs.md)または [Azure Blob Storageの認証情報](https://docs.roboflow.com/datasets/ja/toappurdo/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) ワークスペースの設定から新しいデータソースを作成します。フォームには次の2つのタブがあります：

* 「Connection」には、バケットの詳細とアクセス情報（名前、プロバイダー、バケット、リージョン、Credential）が含まれます。「Credential」ドロップダウンから保存済みのCredentialを選択するか、その横の「+」を使ってフォームを離れずに追加できます。
* 「Mirror Configuration」には、インポート先、ファイルフィルター、ミラーリングの動作が含まれます。

「Bucket」フィールドに入力するのはバケット名のみです（例： `my-bucket`, `s3://my-bucket`）。名前の後にパスが付いたバケット値は受け付けられません。バケットの一部のみをミラーリングするには、次のようなglobパターンを `images/**/*` 「Mirror Configuration」タブの「File Filters」に追加します。Azure Blob Storageでは、コンテナー名にも同じルールが適用されます。

### インポート先の選択

「Mirror Configuration」の「Import Destination」セクションでは、ミラーリングしたファイルの保存先を設定します。各Datasourceのインポート先は1か所のみです。別の場所にインポートするには、Datasourceをもう1つ追加してください。

* 「Workspace」を選択すると、 [Asset Library](https://docs.roboflow.com/platform/workspaces/asset-library)にミラーリングされます。「Import into」ドロップダウンでワークスペースのルートにファイルを保存するか、Projectを選択して、そのProjectにもファイルを追加できます。
* 「Folder」を選択すると、ミラーリングした画像の対象がプロジェクトフォルダーに限定され、そのフォルダーのチームだけが閲覧できます。このオプションは、 [Project Folder Permissions](https://docs.roboflow.com/datasets/ja/guan-li/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` を有効にすると、バケットに存在しなくなったファイル（または glob パターンに一致しなくなったファイル）は、いずれのプロジェクトからも、または別のデータソース設定からも参照されていない場合に、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`            |

サイドカーファイルの制約:

* 最大ファイルサイズ: 256 KB
* 有効なJSONであること
* `null` および `undefined` の値は除外されます

### メタデータ同期の方法

画像のメタデータサイドカー `.json` ファイルがS3で更新されるとき、更新の適用方法は次の2つの設定で制御されます。

* `updateMetadataWhenNewer` （デフォルト: `true`）- サイドカーファイルが保存済みのバージョンより新しい場合に、メタデータを再同期します
* `updateMetadataStrategy` - 同期されたメタデータと、UIまたはAPIから手動で設定したメタデータとの連携方法を制御します。

| 方式                        | 動作                                              |
| ------------------------- | ----------------------------------------------- |
| `mergeBucketWins` （デフォルト） | 両方のソースを統合します。キーが競合する場合は、バケットの値が優先されます           |
| `mergeUserWins`           | 両方のソースを統合します。キーが競合する場合は、ユーザーが設定した値が優先されます       |
| `overwrite`               | バケットのメタデータで既存のメタデータをすべて完全に置き換えます                |
| `untilFirstChange`        | ユーザーがメタデータフィールドを手動で変更するまでバケットから同期し、変更後は同期を停止します |
| `append`                  | バケットから新しいキーのみを追加し、既存のキーは上書きしません                 |

## ミラーリングの手動実行

いつでも、次の画面から手動でミラーリングを実行できます。 [データソース一覧](https://app.roboflow.com/settings/datasources) データソースの横にある再生ボタンをクリックしてください。

手動実行には、次の制限が適用されます。

* **実行中**：同期がすでに実行中の場合、完了するまで別の同期を開始できません。
* **クールダウン**：同期完了後、15分間は手動での再実行ができません。ボタンのツールチップに残り時間が表示されます。次の場合、クールダウンは適用されません。
  * 前回の同期でインポート対象が見つからなかった場合（キューに追加されたファイルが0件、またはすべてのファイルで失敗した場合）。
  * 前回の実行後にデータソースの設定を編集した場合。
  * 前回の実行がエラーを伴って完了した場合。
* **1時間あたりの上限**：データソースは、移動する1時間あたり最大10回まで同期できます。この上限は、クールダウンの適用が免除され、すぐに再実行できる場合にも適用されます。

スケジュール（cron）による同期には、クールダウンと1時間あたりの上限のどちらも適用されません。

### 毎日のスケジュールで実行する

ミラーリングを自動化するには、「ミラー設定」タブの「スケジュール」セクションを開き、「毎日のスケジュールで自動実行する」にチェックを入れます。データソースは24時間ごとに同期されます。スケジュールはデフォルトでオフになっています。

## 同期済みアセットを表示する

各 [データソースの項目](https://app.roboflow.com/settings/datasources) には目のアイコンがあり、クリックすると [アセットライブラリ](https://docs.roboflow.com/platform/workspaces/asset-library) が開き、そのデータソースの画像と動画に絞り込まれます。このアイコンは、データソースの同期が少なくとも1回完了するまで無効です。

いずれかのデータソースから同期されたすべての画像を表示するには、データソース一覧の下部にある「データソースのアセットを表示」をクリックします。このリンクは、少なくとも1つのデータソースが実行されると表示されます。

どちらのリンクからも、タグフィルターがあらかじめ設定されたアセットライブラリに移動します。ワークスペース内の画像のうち、バケットからミラーリングされたものだけを閲覧、検索、管理できます。

## S3互換ストレージ

データソースは、必要なS3 API操作を実装しているS3互換ストレージプロバイダーで使用できます。

これらのプロバイダーを設定するには、次の手順に従います。

1. データソースの「接続」タブで、プロバイダーとして `S3` を選択します。
2. バケット名と認証情報を通常どおり入力します。
3. プロバイダー固有の `endpoint` URLを指定します。
4. リージョンには `auto` またはプロバイダー固有のリージョン値を設定します。

プロバイダーのS3 APIエンドポイントを `endpoint`として使用してください。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                                               | `<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 Compatibility | `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>1回のミラーリング実行のステータスと統計情報を取得します。</td></tr></tbody></table>
