調用ListDatasetFileMetas API對資料集檔案進行多模態檢索-人工智慧平台 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	是	資料集版本名。	v1
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 完成分頁查詢操作。	10
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
DatasetFileMetaIds	array	否	要查詢的中繼資料 ID 列表。
	string	否	中繼資料 ID。	5dc037c8ec0a6fc4e15741328e531bbee036exxxxxxxxx722eff66c38a90e08c
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。	10
QueryExpression	string	否	查詢語句（DSL）是一種用於表達複雜檢索條件的領特定領域語言。它支援分組、布爾邏輯（AND/OR/NOT）、範圍比較（>, >=, <, <=）、屬性存在性（HAS/NOT HAS）、分詞匹配（:）與精確匹配（=）等，適用於進階檢索情境。一般用於較為複雜的進階檢索條件。重要為避免衝突，設定該查詢語句後，建議不要與其他查詢參數混用	(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'
Status	string	否	指定要查詢的中繼資料狀態 ACTIVE: 僅查詢未刪除資料(預設) ALL: 查詢全部資料 DELETED: 僅查詢已邏輯刪除資料	ACTIVE
QueryVideo	string	否	以視頻搜尋時，該參數傳入的視訊檔案的資訊。支援傳入的視訊的可公網訪問的 oss url 格式。格式為：oss://{bucket_name}/{object_path}。其中 bucket_name 為 bucket 名稱，object_path 為檔案在 bucket 中的路徑。說明當 QueryType=VECTOR 或 MIX 時有效。	oss://test-xxx-oss/car/0001.mp4

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 的資料

DSL 查詢屬性支援列表

支援檔案基礎中繼資料屬性、標籤屬性、向量檢索屬性、通用檢索屬性. 所有屬性在查詢條件中都必須是非必選的。

類型的說明：

KEYWORD：僅支援等於、不等於、存在、不存在中的一種或多種
TEXT：僅支援分詞包含、分詞不包含、等於、不等於、存在、不存在中的一種或多種
NUMBER：僅支援範圍查詢、等於、存在、不存在中的一種或多種
DATE：僅支援範圍查詢、存在、不存在中的一種或多種

基礎中繼資料屬性

屬性名稱	內部類型	分詞包含	分詞不包含	等於	不等於	存在/不存在	範圍查詢	AND 邏輯	OR 邏輯
DatasetFileMetaId	KEYWORD	-	-	✅	✅	✅	-	✅	✅
FileName	TEXT	✅	✅	✅	✅	✅	-	✅	✅
FileDir	TEXT	✅	✅	✅	✅	✅	-	✅	✅
FileType	KEYWORD	-	-	✅	✅	✅	-	✅	✅
ContentType	KEYWORD	-	-	✅	✅	✅	-	✅	✅
DataSize	NUMBER	-	-	✅	-	✅	✅	✅	✅
FileUpdateTime	DATE	-	-	-	-	✅	✅	✅	✅
SyncTime	DATE	-	-	-	-	✅	✅	✅	✅
TagUpdateTime	DATE	-	-	-	-	✅	✅	✅	✅
SemanticIndexUpdateTime	DATE	-	-	-	-	✅	✅	✅	✅
Status	KEYWORD	-	-	✅	❌	❌	-	✅	❌

標籤屬性

屬性名稱	內部類型	分詞包含	分詞不包含	等於	不等於	存在/不存在	範圍查詢	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	-	-	✅	-	❌	❌	✅	❌

返回參數

名稱	類型	描述	樣本值
	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        \"Lane line\",\n        \"Water horse\",\n        \"Sunny day\"\n    ],\n    \"user\":\n    [\n        \"Everett\",\n        \"Intelligent driving Dataset 1\",\n        \"Cloudy day\"\n    ],\n    \"user-delete-ai-tags\":\n    [\n        \"Sunny day\"\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",
      "Status": "ACTIVE"
    }
  ],
  "DatasetId": "d-rbvg5*****jhc9ks92\n",
  "WorkspaceId": "105173",
  "DatasetVersion": "v1",
  "MaxResults": 10
}

錯誤碼

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。