roboflow-cloud-storage

面向 Agent： 此技能由 roboflow/computer-vision-skills 编写。如果你的客户端已将其加载为技能（例如通过 Roboflow 插件），请使用该副本。roboflow://skills/<name>/... MCP 资源会为尚未加载此技能的客户端提供相同的技能。

云存储（数据源和凭据）

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

• 凭据 — Roboflow 用于访问存储桶的密钥（在服务端存储并屏蔽，可供多个数据源重复使用）。
• 数据源 — 存储桶镜像配置：指定存储桶（通过凭据访问）、对象（glob 规则）以及同步方式。“数据源”是面向用户的名称；平台会将其存储为存储桶镜像配置。

导入内容会进入工作区。目前，数据源 API 无法指定特定项目／数据集。

只想对文件运行模型／工作流并收集输出，而不将任何内容导入 Roboflow？这属于批处理 — 请参阅 roboflow-batch-processing 技能。镜像也可以与之结合使用：导入的文件会成为 Asset Library 图像，对这些图像进行批量预测则会作为 Asset Library 批处理作业运行（同一技能）。

快速开始 — 一次调用

connect_cloud_storage 一次即可完成整个流程：（可选）创建凭据、创建数据源、验证访问权限并启动首次镜像运行。新设置建议使用此工具。

• 重用凭据：传入 credential_id（来自 credentials_list）。
• 创建新凭据：传入 credential_name + credential_type（密钥通过安全的带外方式收集 — 请参阅“安全性”）。
• 描述要创建的数据源：bucket_type（s3／gcs）、bucket_name、region，以及可选的 mirror_configs glob 规则（请参阅“数据源”）。必须先创建数据源，才能验证或触发任何操作 — 没有数据源就无内容可镜像。
• trigger（默认值为 true）仅在验证通过后启动镜像运行；触发操作会消耗额度。
• 返回 {credentialId, credentialCreated, datasourceId, validation, triggered, batchIds?}。如果已创建新凭据，但后续步骤失败，则会返回 status: "partial" 和相应 ID，你可以使用 credentials_delete／datasource_delete 清理。

凭据

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

密钥（密钥值、服务账号 JSON、密码）通过 MCP elicitation 以带外方式收集，绝不会作为工具参数，也不会出现在对话记录或模型上下文中。credentials_list 只会返回经过屏蔽的非敏感字段。 如果你的客户端无法安全地收集信息，工具会返回 manual_entry_required，并提供在应用中创建凭据的 URL（app.roboflow.com/<workspace>/settings/datasources）；之后调用 credentials_list 获取其 ID。

凭据类型

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（完整的服务账号 JSON）
usernamePassword	兼容 S3 的服务	username、password
apiKey	兼容 S3 的服务	apiKey

AWS PrivateLink（require_vpce） 要求使用 AssumeRoleWithWebIdentity 凭据；否则，服务端会拒绝该数据源。

数据源

存储桶

• bucket_type：s3 或 gcs
• bucket_name（不含 scheme／路径）、region（例如 us-east-1）
• endpoint：兼容 S3 的提供商使用的自定义 URL（仅限 S3）

镜像规则（mirror_configs）

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

• glob_patterns（列表）— 关键字段。选择对象，例如： ["images/**/*.jpg", "batch-*/**"]。设置此字段可避免导入不需要的文件，也可将一个存储桶拆分为多条规则。只有在确实需要导入所有内容时才省略。
• glob_file_path — 替代方案：存储桶中的清单文件路径，其每行列出要导入的对象路径。
• 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 小时一次；仅支持开启或关闭）。

生命周期与验证

1. 创建（datasource_create 或 connect_cloud_storage）。此时尚未镜像任何内容。
2. 验证（datasource_validate）— 检查 listFiles、headFile、 getFile 和每条规则的 headGlobFile；返回 {checks, errors}。运行此操作可在触发前自行诊断凭据或存储桶问题。
3. 触发（datasource_trigger）— 启动镜像任务；会消耗计算／存储额度。返回 {batchIds}。
4. 轮询（使用 batchId 调用 datasource_job_get）— 返回 status （running/completed/failed）、各阶段的 counters、errors 和时间戳。

更新（datasource_update）：仅更改传入的字段；要更改存储桶，请同时传入 bucket_type、bucket_name 和 region。 删除（datasource_delete）：移除配置，但不会删除已镜像的图像。如果删除仍被数据源引用的凭据，其任务将会失败。

可用的 MCP 工具

工具	用途
connect_cloud_storage	端到端流程：凭据 + 数据源 + 验证 + 首次运行
credentials_list	列出经过掩码处理的云存储凭据
get_aws_storage_credential_setup_link	获取用于设置 AWS 存储凭据的 Roboflow 应用链接；请在应用中输入密钥
credentials_delete	删除凭据
datasources_list / datasource_get	列出／检查数据源配置
datasource_create / datasource_update / datasource_delete	管理数据源
datasource_validate	在运行任务前检查存储桶访问权限
datasource_trigger	启动镜像任务（会消耗额度）
datasource_job_get	轮询镜像任务的状态和计数器

相关页面

• roboflow://skills/roboflow-data-management/SKILL — 镜像完成后如何处理图像（标签、数据集拆分、版本、搜索）
• roboflow://skills/roboflow-product-navigation/SKILL — 应用中的 settings/datasources 页面