search-assets

search_media_library searchQuery

在 DAM 上使用严格筛选条件调用 search_media_library。不要先获取大量数据，再在代码中筛选。

先发现字段，再进行猜测

账户可以定义任意自定义元数据字段。用户会输入普通词语（“Nike”“夏季活动”“EMEA”“已批准”），这些词可能是字段名称、选择选项、标签，也可能只是文件名。切勿臆造 "customMetadata.<name>"。

对于你可能放在 name 或 tags 上的每个描述性词语：

1. 调用一次 list_custom_metadata_fields。将该词语与每个字段的 name、label 和 schema.selectOptions 匹配（不区分大小写）。使用字段的 name（而非 label）作为 "customMetadata.<name>"。
2. 使用该词语作为 label 调用 list_client_tags。如果返回标签，则使用返回的标签 name 原样构造 tags IN [...] 筛选条件。
3. 只有在两次调用都没有匹配项时，才回退到 name HAS "…"。字面文件名、扩展名，以及用户明确说“名称为／称作／标题为 X”的内容，无需检查，直接放在 name 上。

未匹配到结果时，直接省略该自定义元数据子句，不要猜测字段。跳过填充词（“文件”“给我显示”“资源”）。

选择类型：SingleSelect → = / IN；MultiSelect → IN / NOT IN。优先使用返回的 selectOptions 值，而非用户输入的原始拼写。文本 → = : HAS；数字／日期 → < <= > >=；布尔值 → 使用不带引号的 true／false 搭配 =。

输入项

输入项	用途
searchQuery	Lucene 筛选条件（见下文）。
path	文件夹范围，例如 /products。
type	file / file-version / folder / all。仅在省略 searchQuery 时生效。
fileType	image / non-image / all。
sort	ASC_/DESC_ + CREATED（默认 ASC_CREATED）、UPDATED、NAME、SIZE、WIDTH、HEIGHT、DURATION、RELEVANCE、ORIGINAL_CREATION_DATE。使用 HAS 时搭配 DESC_RELEVANCE。*_ORIGINAL_CREATION_DATE 按保留字段 _internal_original_created_datetime 排序；没有此值的文件会回退到上传时间。
limit / skip	页面大小（最大 1000）和偏移量。默认页面大小为 20。

将简单的文件夹范围放在 path 中，并使用 fileType 区分文件与非图像文件。设置 searchQuery 时，始终将类型放入 searchQuery 中（type = "folder"，或 (name HAS "logo") AND type = "folder"）。这种情况下会忽略 type 参数，结果默认返回文件。

语法

• 运算符： = : < <= > >= IN NOT IN NOT = HAS EXISTS NOT EXISTS
• 组合： AND、OR。分组： ( ... )
• 引号： 字符串值使用"双引号"；数字和布尔值（true／false）不加引号；customMetadata / embeddedMetadata 字段名必须加引号，例如 "customMetadata.brand"。
• : = 前缀匹配／匹配子文件夹；= = 精确匹配。HAS = 不区分大小写的全文搜索（按词元拆分）。

字段

字段	运算符	值说明
name	= : IN NOT = NOT IN HAS	= 完全匹配（区分大小写），: 前缀匹配，HAS 不区分大小写的全文搜索
tags	IN NOT IN HAS EXISTS NOT EXISTS	同时匹配 tags 和 AITags
type	= IN NOT = NOT IN	"file" | "file-version" | "folder"
id	= IN NOT = NOT IN	fileId 或 folderId
createdAt / updatedAt	= < <= > >= IN NOT = NOT IN	ISO 8601 或相对时间（"1h" "2d" "3w" "4m" "1y"）
width / height	= < <= > >= IN NOT = NOT IN	像素；仅适用于图像
size	= < <= > >= IN NOT = NOT IN	字节数（1024）或 "1mb" / "10kb"
videoDuration	= < <= > >= IN NOT = NOT IN	仅适用于视频。带单位并加引号："30sec" "1.5min" "2hr"（或 s/m/h）；不带引号的数字表示秒
format	= IN	"jpg" "png" "webp" "gif" "svg" "avif" "pdf" "mp4" …
private / published / transparency	=	布尔值，不加引号
createdBy	= IN NOT = NOT IN	上传者邮箱
path	= : IN NOT = NOT IN	= 精确匹配文件夹；: 匹配文件夹及其子文件夹
"customMetadata.<field>"	取决于类型	字段名需加引号。通过 list_custom_metadata_fields 查询。保留字段 _internal_original_created_datetime（Date，标签为 "Original creation date"）仅在启用该字段的账户中列出，且带有 reserved: true
"embeddedMetadata.<field>"	取决于类型	来自文件，而非 DAM 架构。Keywords 使用 IN/EXISTS；DateTimeOriginal 使用日期运算符；LocationTaken 支持地理位置（"40,100 5km"）

示例

name HAS "red dress"
name = "red-dress.jpg"
name : "red-dress"
createdAt > "7d" AND size > "2mb"
tags IN ["sale", "summer"]
tags NOT EXISTS
format IN ["jpg", "webp"]
path : "/sales-banner/"
"customMetadata.brand" = "nike"
"customMetadata.Region" IN ["EMEA"]
"customMetadata.rating" > 4.3
"embeddedMetadata.DateTimeOriginal" > "1y"
videoDuration > "1min" AND format = "mp4"
"customMetadata._internal_original_created_datetime" < "2021-01-01"
(size < "1mb" AND width > 500) OR (tags IN ["summer-sale", "banner"])

用户说“Nike 素材” → list_custom_metadata_fields 找到 brand / 选项中包含 Nike → "customMetadata.brand" = "Nike"。如果字段或标签已匹配，请勿搜索 name HAS "Nike"。

注意事项

• name 的 = / : 区分大小写；使用 HAS 可进行不区分大小写的匹配。
• tags 查询会同时搜索 tags 和 AITags。
• HAS 会按空格/标点拆分词语；最后一个词会进行前缀匹配。请搭配 sort: DESC_RELEVANCE 使用。
• 布尔值（private、published、transparency）不加引号；字符串值需加引号。
• width / height / transparency 仅适用于图像；videoDuration 仅适用于视频。单位为 sec / min / hr，而非 minutes / hours。
• 仅当 list_custom_metadata_fields 返回 _internal_original_created_datetime 时，才按 ASC_ORIGINAL_CREATION_DATE / DESC_ORIGINAL_CREATION_DATE 排序；否则使用 *_CREATED。
• "customMetadata.<field>" 仅匹配账户中定义的字段。整个标记都要加引号。
• 只要设置了 searchQuery，就会忽略 type 工具参数。请改为在 searchQuery 中使用 type = "folder"（或 type IN [...]）。