CreateDataset-对象存储(OSS)-阿里云帮助中心

调用 CreateDataset 接口在已开启元数据管理的 Bucket 上创建一个 Dataset。Dataset 用于承载一组 Object 的元数据索引,并可携带独立的 DatasetConfig 配置内容感知细项。

注意事项

阿里云账号默认拥有创建 Dataset 的权限。如需通过 RAM 用户创建,请确保 RAM 用户拥有 oss:MetaQuery 权限。
调用本接口前,Bucket 必须已通过 OpenMetaQuery 开启元数据管理,且向量检索;否则返回 MetaQueryNotExist 或 InvalidArgument。
同名 Dataset 重复创建返回 ResourceAlreadyExists(HTTP 400)。
当 OpenMetaQuery 时配置了 RouteRule.AutoCreateDataset=True 后,写入命中路由 Tag 的 Object 时会按 Tag Value 自动创建 Dataset,无需提前调用本接口。使用本接口的典型场景是预先创建携带特定 DatasetConfig 的 Dataset。
WorkflowParameters 为兼容旧版本的基础工作流开关。后续 AI 内容感知新能力不再通过该字段演进,新接入建议使用 datasetConfig。
如果创建 Dataset 时不传 datasetConfig,系统不会把 OpenMetaQuery 中配置的 DatasetConfig 复制到该 Dataset 的持久化配置中。需要 Dataset 拥有可查询、可维护的独立配置时,请在创建或更新时显式传入 datasetConfig。
请求体为空。description、workflowParameters、datasetConfig 均通过 URL Query Parameter 传入。

请求语法

POST /?metaQuery&action=createDataset&datasetName=DatasetName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

请求头

此接口仅涉及公共请求头。更多信息,请参见公共请求头(Common Request Headers)。

请求元素

名称	类型	是否必选	示例值	描述
datasetName	字符串	是	photos-2026	待创建的 Dataset 名称。长度 1 到 128 字符,字符集 `[a-zA-Z0-9_-]`。
description	字符串	否	2026 年图库	Dataset 描述文本。包含非 ASCII 字符时需 URL 编码。长度不超过 256 字符。
workflowParameters	WorkflowParameter 数组	否	[{"Name":"VideoInsightEnable","Value":"True"}]	兼容旧版本 AI 内容感知基础开关。通过 URL Query String 传递时需 JSON 序列化并 URL 编码。后续新功能不再通过该字段演进,推荐使用 `datasetConfig`。子节点:WorkflowParameter
WorkflowParameter	容器	否	不涉及	单个工作流参数配置。子节点:Name、Value 父节点:workflowParameters
Name	字符串	是	VideoInsightEnable	工作流参数名。可选值:VideoInsightEnable、ImageInsightEnable、UserDefinedLabelsEnable。父节点:WorkflowParameter
Value	字符串	是	True	工作流参数取值。取值 True / False。父节点:WorkflowParameter
datasetConfig	DatasetConfig 对象	否	{"Insights":{"Language":"en"}}	当前 Dataset 的内容感知细项与智能分组配置。通过 URL Query String 传递时需 JSON 序列化并 URL 编码。字段结构与 DatasetConfig 数据结构一致。子节点:Insights、ReverseImage、SmartCluster

响应头

此接口仅涉及公共响应头。更多信息,请参见公共响应头(Common Response Headers)。

响应元素

名称

类型

是否必选

示例值

描述

CreateDatasetResponse

容器

是

不涉及

接口响应的根容器。

子节点:Dataset

Dataset

容器

是

不涉及

已创建 Dataset 的完整信息。详细字段见 Dataset 数据结构。

父节点:CreateDatasetResponse

示例

请求示例

最简创建:

POST /?metaQuery&action=createDataset&datasetName=photos-2026 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

携带 datasetConfig 创建内容感知 Dataset:

POST /?metaQuery&action=createDataset&datasetName=videos-en&datasetConfig=%7B%22Insights%22%3A%7B%22Language%22%3A%22en%22%2C%22Video%22%3A%7B%22Caption%22%3A%7B%22Enable%22%3Atrue%7D%7D%7D%7D HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

兼容旧版本的 workflowParameters 创建示例。该方式仅用于存量基础开关,后续新功能不再通过 workflowParameters 演进:

POST /?metaQuery&action=createDataset&datasetName=videos-basic&workflowParameters=%5B%7B%22Name%22%3A%22VideoInsightEnable%22%2C%22Value%22%3A%22True%22%7D%2C%7B%22Name%22%3A%22ImageInsightEnable%22%2C%22Value%22%3A%22True%22%7D%5D HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

workflowParameters 参数 URL 解码后:

[
  {"Name": "VideoInsightEnable", "Value": "True"},
  {"Name": "ImageInsightEnable", "Value": "True"}
]

返回示例

HTTP/1.1 200 OK
x-oss-request-id: 64C8B6F4E7C5A3A8B9D6E7F1
Date: Wed, 20 May 2026 08:00:01 GMT
Content-Type: application/xml
Server: AliyunOSS

<?xml version="1.0" encoding="UTF-8"?>
<CreateDatasetResponse>
  <Dataset>
    <DatasetName>photos-2026</DatasetName>
    <Description>2026 年图库</Description>
    <CreateTime>2026-05-20T08:00:00.000+08:00</CreateTime>
    <UpdateTime>2026-05-20T08:00:00.000+08:00</UpdateTime>
    <DatasetMaxFileCount>100000000</DatasetMaxFileCount>
    <DatasetMaxEntityCount>10000000000</DatasetMaxEntityCount>
    <DatasetMaxRelationCount>100000000000</DatasetMaxRelationCount>
    <DatasetMaxTotalFileSize>90000000000000000</DatasetMaxTotalFileSize>
    <DatasetConfig>
      <Insights>
        <Language>en</Language>
        <Video>
          <Caption>
            <Enable>True</Enable>
          </Caption>
        </Video>
      </Insights>
    </DatasetConfig>
  </Dataset>
</CreateDatasetResponse>