roboflow-cloud-storage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

For agents: This skill is authored in
roboflow/computer-vision-skills
. If your client already has it loaded as a skill (for example from a Roboflow plugin), use that copy. The
skill://roboflow/<name>/SKILL.md
MCP resources serve the same skills for clients that don't have them loaded.

对于 Agent： 此 skill 编写于
roboflow/computer-vision-skills
。如果你的客户端已经将其作为 skill 加载（例如通过 Roboflow plugin），请使用该副本。
skill://roboflow/<name>/SKILL.md
MCP resources 为尚未加载这些 skill 的客户端提供相同的 skills。

Cloud Storage (Datasources & Credentials)

云存储（Datasources 与 Credentials）

Mirror a cloud bucket's contents into a Roboflow workspace so new objects flow in automatically. Two pieces work together:

Credential — the secret Roboflow uses to reach the bucket (stored, masked server-side, reusable across datasources).
Datasource — a bucket-mirror configuration: which bucket (via a credential), which objects (glob rules), and how they sync. "Datasource" is the user-facing name; the platform stores it as a bucket-mirror config.

Imports land at the workspace level. The datasource API cannot target a specific project/dataset today.

Only want to run a model/Workflow over the files and collect the outputs, without importing anything into Roboflow? That is batch processing — see the
roboflow-batch-processing
skill. Mirroring composes with it too: imported files become Asset Library images, and bulk predictions over them run as Asset Library batch processing jobs (same skill).

将云存储桶中的内容镜像到 Roboflow 工作区，使新对象能够自动流入。以下两部分协同工作：

Credential — Roboflow 用于访问存储桶的密钥（存储在服务器端并经过掩码处理，可在多个数据源之间复用）。
Datasource — 存储桶镜像配置：指定使用哪个 credential 访问哪个存储桶、选择哪些对象（glob 规则），以及如何进行同步。“Datasource”是面向用户的名称；平台将其存储为 bucket-mirror 配置。

导入内容会落在 workspace 层级。目前 datasource API 无法指定特定的 project/dataset。

只需要对文件运行 model/Workflow 并收集输出，而不向 Roboflow 导入任何内容？那属于 batch processing——请参阅
roboflow-batch-processing
skill。Mirroring 也可以与其组合使用：导入的文件会成为 Asset Library 图像，对它们进行批量预测则作为 Asset Library batch processing 任务运行（使用同一 skill）。

Fast path — one call

快速路径——一次调用

connect_cloud_storage

does the whole flow in one shot: (optionally) create a credential, create the datasource, validate access, and start the first mirror run. Prefer it for new setups.

Reuse a credential: pass
```
credential_id
```
(from
```
credentials_list
```
).
Create a new credential: pass
```
credential_name
```
+
```
credential_type
```
(the secret is collected securely out-of-band — see Security).
Describe the datasource so it can be created first:
```
bucket_type
```
(
```
s3
```
/
```
gcs
```
),
```
bucket_name
```
,
```
region
```
, plus optional
```
mirror_configs
```
glob rules (see Datasources). The datasource must exist before anything can be validated or triggered — there is nothing to mirror without it.
```
trigger
```
(default true) starts a mirror run only if validation passes; triggering consumes credits.

Returns

{credentialId, credentialCreated, datasourceId, validation, triggered, batchIds?}

. If a new credential was created but a later step failed, you get

status: "partial"

with the ids so you can clean up with

credentials_delete

datasource_delete

connect_cloud_storage

可一次完成整个流程：（可选）创建 credential、创建 datasource、验证访问权限并启动首次镜像同步。新建配置时优先使用此方式。

复用 credential：传入
```
credential_id
```
（来自
```
credentials_list
```
）。
创建新 credential：传入
```
credential_name
```
+
```
credential_type
```
（密钥通过安全的带外方式收集——参见安全部分）。
描述 datasource，以便先创建它：
```
bucket_type
```
（
```
s3
```
/
```
gcs
```
）、
```
bucket_name
```
、
```
region
```
，以及可选的
```
mirror_configs
```
glob 规则（参见 Datasources）。必须先存在 datasource，才能进行验证或触发；没有 datasource 就无法镜像任何内容。
```
trigger
```
（默认为 true）仅在验证通过后启动镜像同步；触发操作会消耗 credits。

{credentialId, credentialCreated, datasourceId, validation, triggered, batchIds?}

。如果已创建新 credential，但后续步骤失败，则会返回

status: "partial"

及相关 ids，以便使用

credentials_delete

datasource_delete

进行清理。

Credentials

Security — secrets never enter the chat

安全——密钥绝不进入聊天

The secret (keys, service-account JSON, password) is collected out-of-band via MCP elicitation, never as a tool argument and never in the transcript or model context.

credentials_list

returns only masked, non-secret fields. If your client can't elicit securely, the tool returns

manual_entry_required

with a URL to create the credential in the app (

app.roboflow.com/<workspace>/settings/datasources

), then call

credentials_list

to get its id.

密钥（访问密钥、service-account JSON、密码）通过 MCP elicitation 带外收集，绝不会作为工具参数传入，也不会出现在对话记录或模型上下文中。

credentials_list

仅返回经过掩码处理的非敏感字段。如果你的客户端无法安全地执行 elicitation，工具将返回

manual_entry_required

以及一个用于在应用中创建 credential 的 URL（

app.roboflow.com/<workspace>/settings/datasources

），随后调用

credentials_list

获取其 id。

Credential types

Credential 类型

`credential_type`	Provider	Secret fields collected
`IAM`	AWS S3	`accessKeyId` , `secretAccessKey` , `sessionToken?`
`AssumeRole`	AWS S3	`roleArn` , `externalId` , `sessionName?`
`AssumeRoleWithWebIdentity`	AWS S3	`roleArn` , `webIdentityAudience` , `webIdentityRoleArn` , `externalId` , `sessionName?`
`gcs`	Google Cloud Storage	`projectId` , `credentialFile` (full service-account JSON)
`usernamePassword`	S3-compatible	`username` , `password`
`apiKey`	S3-compatible	`apiKey`

AWS PrivateLink (
require_vpce
) requires an
AssumeRoleWithWebIdentity
credential; the server rejects the datasource otherwise.

`credential_type`	服务商	收集的密钥字段
`IAM`	AWS S3	`accessKeyId` , `secretAccessKey` , `sessionToken?`
`AssumeRole`	AWS S3	`roleArn` , `externalId` , `sessionName?`
`AssumeRoleWithWebIdentity`	AWS S3	`roleArn` , `webIdentityAudience` , `webIdentityRoleArn` , `externalId` , `sessionName?`
`gcs`	Google Cloud Storage	`projectId` , `credentialFile` （完整的 service-account JSON）
`usernamePassword`	S3 兼容存储	`username` , `password`
`apiKey`	S3 兼容存储	`apiKey`

AWS PrivateLink（
require_vpce
）要求使用
AssumeRoleWithWebIdentity
credential；否则服务器会拒绝该 datasource。

Datasources

Bucket

```
bucket_type
```
:
```
s3
```
or
```
gcs
```
```
bucket_name
```
(no scheme/path),
```
region
```
(e.g.
```
us-east-1
```
)
```
endpoint
```
: custom URL for S3-compatible providers (S3 only)

```
bucket_type
```
：
```
s3
```
或
```
gcs
```
```
bucket_name
```
（不包含 scheme/path）、
```
region
```
（例如
```
us-east-1
```
）
```
endpoint
```
：S3 兼容服务提供商的自定义 URL（仅限 S3）

Mirror rules (

mirror_configs

)

镜像规则（

mirror_configs

）

Optional list; omit to mirror the whole bucket with default settings. Each rule selects a subset and controls sync behavior:

glob_patterns
(list) — the key field. Selects objects, e.g.
```
["images/**/*.jpg", "batch-*/**"]
```
. Set it to avoid importing unwanted files or to split a bucket into multiple rules. Omit only when you truly want everything.
```
glob_file_path
```
— alternative: path to a manifest file in the bucket whose lines list object paths to import.
```
id
```
— rule id (auto-generated; pass an existing id on update to edit in place).

settings

(omitted keys use server defaults):

```
removeOrphanedSourcesWhenDisappeared
```
(default true) — delete mirrored images when the source object is removed.

namingStrategy

(

fullPath

fileName

eTag

metadata

, default

fullPath

);

namingStrategyMetadataKey

required when

metadata

updateImageWhenNewer

(true) /

updateImageStrategy

(

overwrite

updateMetadataWhenNewer

(true) /

updateMetadataStrategy

(

mergeBucketWins

default; also

overwrite

merge

mergeUserWins

untilFirstChange

append

```
runScheduledEvery
```
(hours, default 0 = off) — >0 enables a recurring mirror (fixed 24h cadence today; only on/off is honored).

可选列表；如果省略，则使用默认设置镜像整个存储桶。每条规则用于选择对象子集并控制同步行为：

glob_patterns
（列表）——核心字段。用于选择对象，例如
```
["images/**/*.jpg", "batch-*/**"]
```
。设置该字段可避免导入不需要的文件，或将一个存储桶拆分为多条规则。只有确实需要导入全部内容时才可省略。
```
glob_file_path
```
——备选项：存储桶内 manifest 文件的路径，该文件的每一行列出要导入的对象路径。
```
id
```
——规则 id（自动生成；更新时传入已有 id 可原地编辑规则）。
```
settings
```
（省略的键使用服务器默认值）：
- ```
removeOrphanedSourcesWhenDisappeared
```
  （默认 true）——源对象被删除时，同时删除已镜像的图像。
- ```
namingStrategy
```
  （
```
fullPath
```
  |
```
fileName
```
  |
```
eTag
```
  |
```
metadata
```
  ，默认
```
fullPath
```
  ）；当使用
```
metadata
```
  时，必须设置
```
namingStrategyMetadataKey
```
  。
- ```
updateImageWhenNewer
```
  （true）/
```
updateImageStrategy
```
  （
```
overwrite
```
  ）。
- ```
updateMetadataWhenNewer
```
  （true）/
```
updateMetadataStrategy
```
  （
```
mergeBucketWins
```
  为默认值；还支持
```
overwrite
```
  |
```
merge
```
  |
```
mergeUserWins
```
  |
```
untilFirstChange
```
  |
```
append
```
  ）。
- ```
runScheduledEvery
```
  （小时，默认 0 = 关闭）——大于 0 时启用周期性镜像同步（目前固定为每 24 小时一次；仅支持开启或关闭）。

Lifecycle & validation

生命周期与验证

Create (
```
datasource_create
```
, or
```
connect_cloud_storage
```
). Nothing is mirrored yet.
Validate (
```
datasource_validate
```
) — checks
```
listFiles
```
,
```
headFile
```
,
```
getFile
```
, and per-rule
```
headGlobFile
```
; returns
```
{checks, errors}
```
. Run it to self-diagnose a bad credential/bucket before triggering.
Trigger (
```
datasource_trigger
```
) — starts the mirror job; consumes compute/storage credits. Returns
```
{batchIds}
```
.
Poll (
```
datasource_job_get
```
with a
```
batchId
```
) —
```
status
```
(running/completed/failed), per-stage
```
counters
```
,
```
errors
```
, timestamps.

Update (

datasource_update

): only fields you pass change; to change the bucket pass

bucket_type

bucket_name

region

together. Delete (

datasource_delete

): removes the config, not already-mirrored images. Deleting a credential still referenced by a datasource makes its runs fail.

创建（
```
datasource_create
```
或
```
connect_cloud_storage
```
）。此时尚未镜像任何内容。
验证（
```
datasource_validate
```
）——检查
```
listFiles
```
、
```
headFile
```
、
```
getFile
```
以及每条规则的
```
headGlobFile
```
；返回
```
{checks, errors}
```
。触发前运行此步骤，可自行诊断 credential 或存储桶配置问题。
触发（
```
datasource_trigger
```
）——启动镜像同步任务；消耗 compute/storage credits。返回
```
{batchIds}
```
。
轮询（使用
```
batchId
```
调用
```
datasource_job_get
```
）——查询
```
status
```
（running/completed/failed）、各阶段的
```
counters
```
、
```
errors
```
和时间戳。

更新（

datasource_update

）：仅修改传入的字段；要更改存储桶，必须同时传入

bucket_type

bucket_name

region

。删除（

datasource_delete

）：移除配置，不会删除已经镜像的图像。如果删除仍被 datasource 引用的 credential，其运行任务将会失败。

MCP Tools Available

可用的 MCP Tools

Tool	Purpose
`connect_cloud_storage`	End-to-end: credential + datasource + validate + first run
`credentials_list`	List masked cloud-storage credentials
`get_aws_storage_credential_setup_link`	Get a Roboflow app link for AWS storage credential setup; enter secrets in the app
`credentials_delete`	Delete a credential
`datasources_list` / `datasource_get`	List / inspect datasource configs
`datasource_create` / `datasource_update` / `datasource_delete`	Manage a datasource
`datasource_validate`	Check bucket access before a run
`datasource_trigger`	Start a mirror run (consumes credits)
`datasource_job_get`	Poll a mirror run's status and counters

Tool	用途
`connect_cloud_storage`	端到端流程：credential + datasource + 验证 + 首次运行
`credentials_list`	列出经过掩码处理的云存储 credentials
`get_aws_storage_credential_setup_link`	获取用于设置 AWS 存储 credential 的 Roboflow 应用链接；在应用中输入密钥
`credentials_delete`	删除 credential
`datasources_list` / `datasource_get`	列出或查看 datasource 配置
`datasource_create` / `datasource_update` / `datasource_delete`	管理 datasource
`datasource_validate`	在运行前检查存储桶访问权限
`datasource_trigger`	启动镜像同步任务（消耗 credits）
`datasource_job_get`	轮询镜像同步任务的状态和 counters

roboflow-cloud-storage

Original

Translation

Cloud Storage (Datasources & Credentials)

云存储（Datasources 与 Credentials）

Fast path — one call

快速路径——一次调用

Credentials

Credentials

Security — secrets never enter the chat

安全——密钥绝不进入聊天

Credential types

Credential 类型

Datasources

Datasources

Bucket

Bucket

Mirror rules (
`mirror_configs`
)

镜像规则（
`mirror_configs`
）

Lifecycle & validation

生命周期与验证

MCP Tools Available

可用的 MCP Tools

Related Pages

相关页面

roboflow-cloud-storage

Original

Translation

Cloud Storage (Datasources & Credentials)

云存储（Datasources 与 Credentials）

Fast path — one call

快速路径——一次调用

Credentials

Credentials

Security — secrets never enter the chat

安全——密钥绝不进入聊天

Credential types

Credential 类型

Datasources

Datasources

Bucket

Bucket

Mirror rules (mirror_configs)

镜像规则（mirror_configs）

Lifecycle & validation

生命周期与验证

MCP Tools Available

可用的 MCP Tools

Related Pages

相关页面

Mirror rules (
`mirror_configs`
)

镜像规则（
`mirror_configs`
）