ListDatasetFileMetas - 获取数据集文件元数据列表_人工智能平台 PAI(PAI)-阿里云帮助中心

查询数据集文件列表。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

paidataset:ListDatasetFileMetas

list

*全部资源

*

无

请求语法

GET /api/v1/datasets/{DatasetId}/datasetfilemetas HTTP/1.1

请求参数

名称

类型

必填

描述

示例值

DatasetId

string

是

数据集 ID。如何获取数据集 ID，详情请参见 ListDatasets 。

d-rbvg5*****jhc9ks92

DatasetVersion

string

是

数据集版本名。

WorkspaceId

string

是

数据集所在工作空间 ID。如何获取工作空间 ID，请参见 ListWorkspaces 。

105173

QueryType

string

否

检索类型。

MIX：混合检索（默认值）。
TAG：仅标签检索。
VECTOR：仅向量检索。

枚举值：

TAG :
TAG
MIX :
MIX
VECTOR :
VECTOR

MIX

QueryText

string

否

待搜索文本内容。

A fallen water

TopK

integer

否

检索结果返回数量，最多只返回 TopK 个检索结果。

说明

当 QueryType=VECTOR 或 MIX 时有效。

100

ScoreThreshold

number

否

相似度分数过滤。只返回大于 ScoreThreshold 的结果。

说明

当 QueryType=VECTOR 或 MIX 时有效。

0.6

PageSize deprecated

integer

否

每页数量。如果同时传入 MaxResults，则以 MaxResults 数量为准。

说明

该参数即将下线，推荐您使用 NextToken 与 MaxResults 完成分页查询操作。

NextToken

string

否

分页游标标识。

说明

如果不设置该参数，则表示获取第一页的数据。当该参数有返回值时，说明还有下一页，您可以将返回的 NextToken 作为参数再次请求获得下一页的数据，直到返回为 Null 为止，表示获取到了所有的数据。

90a6ee35-****-4cd4-927e-1f45e1cb8b62_1729644433000

SortBy

string

否

分页查询时的排序字段，缺省时按检索时相关性由高到低排序。其他取值如下。

FileCreateTime：按文件创建时间。
FileUpdateTime：按文件最后修改时间。

枚举值：

FileCreateTime :
FileCreateTime
FileUpdateTime :
FileUpdateTime

FileCreateTime

Order

string

否

分页查询时，对指定的排序字段进行升序或降序，与 SortBy 结合使用。默认 DESC。

ASC：升序。
DESC：降序。

枚举值：

ASC :
ASC
DESC :
DESC

DESC

EndFileUpdateTime

string

否

用于指定查询的起始文件更新时间。ISO 8601 格式的 UTC 时间戳。

2025-01-12T14:36:01.000Z

StartFileUpdateTime

string

否

用于指定查询的结束文件更新时间。ISO 8601 格式的 UTC 时间戳。

2025-01-12T14:36:01.000Z

QueryImage

string

否

以图搜图时，该参数传入图片的信息。

支持传入图片的可公网访问的 oss url 格式。格式为：oss://{bucket_name}/{object_path}。其中 bucket_name 为 bucket 名称，object_path 为文件在 bucket 中的路径。

说明

当 QueryType=VECTOR 或 MIX 时有效。

oss://test-xxx-oss/car/0001.png

ThumbnailMode

string

否

图片缩略图的模式，当前仅 OSS 文件支持缩略图：

等比例缩小: p_{percentage}, percentage 表示期望的缩放比例，取值范围为[1, 100] 。示例：p_50 表示使用原始文件的 50%大小作为缩略图。
宽度固定，高度自适应缩小: w_{width}, width 表示期望的图片宽度，取值范围为[1, 16384]。示例：w_200 表示将图片宽度固定为 200 像素，高度自适应进行缩小。
高度固定，宽度自适应缩小：h_{height}, height 表示期望的图片高度，取值范围为[1, 16384]。示例：h_100 表示将图片高度固定为 100 像素，宽度自适应进行缩小。
固定宽高，缩略填充：m_pad,w_{height},h_{height},color_{RGB}, m_pad 表示图片缩放为指定 w 与 h 的矩形内的最大图片，RGB 表示指定居中填充空白部分的颜色，若不设置该参数，默认用白色填充。width 表示期望的图片宽度，height 表示期望的图片高度。width 和 height 的取值范围都为[1,16384]。示例:
固定宽高，居中裁剪：m_fill,w_{width},h_{height}。m_fill 表示图片等比缩放为延伸出指定 w 与 h 的矩形框外的最小图片，超出的部分进行居中裁剪。width 表示期望的图片宽度，height 表示期望的图片高度。width 和 height 的取值范围都为[1,16384]示例：m_fill,w_100,h_100 表示将图片宽度和高度都固定为 100 像素进行居中裁剪缩放。
强制宽高缩放: m_fixed,w_{height},h_{height}，width 表示期望的图片宽度，height 表示期望的图片高度。width 和 height 的取值范围都为[1,16384]。示例：m_fixed,w_100,h_100 表示将图片宽度和高度都固定为 100 像素进行强制宽高缩放。

w_100

QueryTagsIncludeAll

array

否

表示“同时包含以下标签”检索条件。用户可以选择多个标签，查询结果必须同时满足这些标签。如果为空，则不应用此条件。数组使用逗号分隔。

说明

当 QueryType=TAG 或 MIX 时有效。当 QueryType=TAG 时会将 QueryText 加入到该条件下。

string

否

标签名。

Lane line

QueryTagsIncludeAny

array

否

表示“包含以下任意标签”检索条件。用户可以选择多个标签，查询结果只需满足其中一个即可。如果为空，则不应用此条件。数组使用逗号分隔。

说明

当 QueryType=TAG 或 MIX 时有效。

string

否

标签名。

Lane line

QueryTagsExclude

array

否

表示“排除以下标签”检索条件。用户可以选择多个标签，查询结果中不能包含这些标签。如果为空，则不应用此条件。

说明

当 QueryType=TAG 或 MIX 时有效。

string

否

标签名。

Lane line

QueryFileName

string

否

文件名检索条件。支持模糊检索。

car

QueryFileDir

string

否

文件目录检索条件。支持模糊检索。

cars/20250221/

QueryFileTypeIncludeAny

array

否

表示“包含以下任意文件类型”检索条件。用户可以选择多个文件类型，查询结果只需满足其中一个即可。如果为空，则不应用此条件。数组使用逗号分隔。

string

否

文件类型。

image

QueryContentTypeIncludeAny

array

否

表示“包含以下任意文件内容类型”检索条件。用户可以选择多个文件内容类型，查询结果只需满足其中一个即可。如果为空，则不应用此条件。数组使用逗号分隔。

string

否

文件内容类型。

image/jpeg

StartTagUpdateTime

string

否

用于指定查询的起始标签最后更新时间。ISO 8601 格式的 UTC 时间戳。

2025-01-12T14:36:01.000Z

EndTagUpdateTime

string

否

用于指定查询的结束标签最后更新时间。ISO 8601 格式的 UTC 时间戳。

2025-01-12T14:36:01.000Z

MaxResults

integer

否

使用 NextToken 方式查询时，每次最多返回的结果数。取值范围：1~100。默认值：10。

QueryExpression

string

否

查询语句（DSL）是一种用于表达复杂检索条件的领域特定语言。它支持分组、布尔逻辑（AND/OR/NOT）、范围比较（>, >=, <, <=）、属性存在性（HAS/NOT HAS）、分词匹配（:）与精确匹配（=）等，适用于高级检索场景。一般用于较为复杂的高级检索条件。

重要为避免冲突，设置该查询语句后，建议不要与其他查询参数混用

DSL 查询语法说明：

keyword	说明	范例
:	分词匹配	`FileName:'车道线'` 查找文件名分词后包含“车道线”的数据
NOT :	分词不匹配	`NOT FileName : '车道线'` 查找文件名分词后不包含“车道线”的数据
=	精确值匹配	`FileType='image'` 查找文件类型为“image”的数据（精确匹配）
NOT =	精确值排除	`NOT FileType = 'video'` 查找所有 FileType 不等于"video"的数据
HAS	存在	`HAS SemanticIndexJobId` 查找所有存在 SemanticIndexJobId 属性的数据
NOT HAS	不存在	`NOT HAS SemanticIndexJobId` 查找所有不存在 SemanticIndexJobId 属性的数据
""	对值的字符串类型进行包裹	单双引号效果一致
()	分组操作	`(FileName:'black' AND ContentType='image/jpeg') OR (FileName:'white' AND ContentType='image/png')` 查找 FileName 为模糊匹配 black 并且 ContentType 为 image/jpeg 或者 FileName 为模糊匹配 white 并且 ContentType 为 image/png
>	范围查询：大于	`FileUpdateTime> '2025-01-16T11:52:56.000Z' AND DataSize >= 12345` 文件最后修改时间在 2025-01-16T11:52:56.000Z 之后的并且文件大小大于等于 12345 字节
>=	范围查询：大于等于	同上
<	范围查询：小于	`FileUpdateTime < '2025-01-16T11:52:56.000Z' AND DataSize <= 12345` 文件最后修改时间在 2025-01-16T11:52:56.000Z 之前并且文件大小小于等于 12345 字节
<=	范围查询：小于等于	同上
AND	并且大小写都支持	`FileType='image' AND ContentType:'image/png'` 查找文件类型为 image 且文件格式为 png 的图片
OR	或者大小写都支持	`FileType='image' OR FileType='video'` 查找文件类型为 image 或 video 的数据

属性支持列表

支持文件基础元数据属性、标签属性、向量检索属性、通用检索属性. 所有属性在查询条件中都必须是非必选的。

类型的说明：

KEYWORD：仅支持等于、不等于、存在、不存在中的一种或多种
TEXT：仅支持分词包含、分词不包含、等于、不等于、存在、不存在中的一种或多种
NUMBER：仅支持范围查询、等于、存在、不存在中的一种或多种
DATE：仅支持范围查询、存在、不存在中的一种或多种

基础元数据属性

属性名	内部类型	分词包含	分词不包含	等于	不等于	存在/不存在	范围查询	AND 逻辑	OR 逻辑
DatasetFileMetaId	KEYWORD	-	-	✅	✅	✅	-	✅	✅
FileName	TEXT	✅	✅	✅	✅	✅	-	✅	✅
FileDir	TEXT	✅	✅	✅	✅	✅	-	✅	✅
FileType	KEYWORD	-	-	✅	✅	✅	-	✅	✅
ContentType	KEYWORD	-	-	✅	✅	✅	-	✅	✅
DataSize	NUMBER	-	-	✅	-	✅	✅	✅	✅
SemanticIndexUpdateTime	KEYWORD	-	-	✅	✅	✅	-	✅	✅
FileUpdateTime	DATE	-	-	-	-	✅	✅	✅	✅
SyncTime	DATE	-	-	-	-	✅	✅	✅	✅
TagUpdateTime	DATE	-	-	-	-	✅	✅	✅	✅
SemanticIndexUpdateTime	DATE	-	-	-	-	✅	✅	✅	✅

标签属性

属性名	内部类型	分词包含	分词不包含	等于	不等于	存在/不存在	范围查询	AND 逻辑	OR 逻辑
Tags.ai	KEYWORD	-	-	✅	✅	✅	-	✅	✅
Tags.user	KEYWORD	-	-	✅	✅	✅	-	✅	✅
Tags.all	KEYWORD	-	-	✅	✅	✅	-	✅	✅

向量查询属性

属性名	内部类型	分词包含	分词不包含	等于	不等于	存在/不存在	范围查询	AND 逻辑	OR 逻辑
Content	TEXT	✅	-	❌	❌	❌	-	✅	❌
TopK	NUMBER	-	-	✅	-	❌	❌	✅	❌
ScoreThreshold	NUMBER	-	-	✅	-	❌	❌	✅	❌

通用查询属性

属性名	内部类型	分词包含	分词不包含	等于	不等于	存在/不存在	范围查询	AND 逻辑	OR 逻辑
QueryType	KEYWORD	-	-	✅	❌	❌	-	✅	❌
SignMode	KEYWORD	-	-	✅	❌	❌	-	✅	❌
ThumbnailMode	KEYWORD	-	-	✅	❌	❌	-	✅	❌
SortBy	KEYWORD	-	-	✅	❌	❌	-	✅	❌
Order	KEYWORD	-	-	✅	❌	❌	-	✅	❌
NextToken	KEYWORD	-	-	✅	❌	❌	-	✅	❌
MaxResults	NUMBER	-	-	✅	-	❌	❌	✅	❌

(FileUpdateTime > '2025-02-28T00:00:00Z' AND FileUpdateTime < '2025-05-30T09:27:29Z') AND FileDir:'blue_car' AND NOT FileName="toyota.jpg" AND (( Tags.all='lane line' AND Tags.all='barrier gate') OR NOT Tags.user='rainy days' ) AND HAS SemanticIndexJobId AND Content:'a fallen water horse' AND TopK=100 AND SignMode='PUBLIC'

返回参数

名称	类型	描述	示例值
	object	请求结果。
TotalCount	integer	返回数据总条数	123
PageSize `deprecated`	integer	当前页大小。	30
NextToken	string	分页游标的标识。如果匹配查询条件的返回结果超过了分页大小，则会返回这个分页游标。如果需要获取下一页数据，将返回的游标值作为请求参数即可，直到无游标值返回，表示已经获取了全部数据。	90******-f5c5-4cd4-927e-1f45e1cb8b62_1729644433000
DatasetFileMetas	array	数据集文件元数据详情列表。
	DatasetFileMeta	数据集文件元数据详情。
DatasetId	string	数据集 ID。	d-rbvg5*****jhc9ks92
WorkspaceId	string	工作空间 ID。	105173
DatasetVersion	string	数据集版本名。	v1
MaxResults	integer	使用 NextToken 方式查询时，每次最多返回的结果数。	10

示例

正常返回示例

JSON格式

{
  "TotalCount": 123,
  "PageSize": 30,
  "NextToken": "90******-f5c5-4cd4-927e-1f45e1cb8b62_1729644433000",
  "DatasetFileMetas": [
    {
      "DatasetFileMetaId": "07914c9534586e4e7aa6e9dbca5009082df******fd8a0d857b33296c59bf6",
      "Uri": "oss://test-bucket/dataset/cat.png",
      "FileName": "cat.png",
      "DownloadUrl": "https://test-bucket.oss-cn-shanghai.aliyuncs.com/dataset/cat.png?Expires=171280****&OSSAccessKeyId=LTAI************&Signature=****jZcXOn7FHMCT1DLE22NuNjs%3D",
      "Score": 0.6,
      "DataSize": 120000,
      "FileFingerPrint": "D41D8CD98F*****E9800998ECF8\n",
      "FileUpdateTime": "2025-01-12T14:36:01Z",
      "Tags": "{\n    \"ai\":\n    [\n        \"车道线\",\n        \"水马\",\n        \"晴天\"\n    ],\n    \"user\":\n    [\n        \"EverettLi\",\n        \"智能驾驶数据集1\",\n        \"阴天\"\n    ],\n    \"user-delete-ai-tags\":\n    [\n        \"晴天\"\n    ]\n}",
      "ThumbnailUrl": "https://test-bucket.oss-cn-shanghai.aliyuncs.com/dataset/cat.png?Expires=171280****&OSSAccessKeyId=LTAI************&Signature=****jZcXOn7FHMCT1DLE22NuNjs%3D",
      "MetaAttributes": "{     \"ImageHeight\": 400,     \"ImageWidth\": 800 }",
      "SyncTime": "2021-01-12T14:36:01.000Z",
      "TagUpdateTime": "2021-01-12T14:36:01.000Z",
      "SemanticIndexJobId": "dsjob-klfwtjto****scvt3",
      "SemanticIndexUpdateTime": "2021-01-12T14:36:01.000Z",
      "FileCreateTime": "2021-01-12T14:36:01.000Z",
      "FileType": "image",
      "ContentType": "image/jpeg"
    }
  ],
  "DatasetId": "d-rbvg5*****jhc9ks92\n",
  "WorkspaceId": "105173",
  "DatasetVersion": "v1",
  "MaxResults": 10
}

错误码

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。