Smart Folder

Smart Folder API 允許您列出、建立、更新、刪除智慧型資料夾，並查詢符合條件的項目。

此功能尚未發佈：此 API 需要 Eagle 4.0 Build 22 或更高版本。詳細發佈時間請關注 Eagle 官網。

端點概覽

方法	端點	說明
GET	/api/v2/smartFolder/get	列出智慧型資料夾
POST	/api/v2/smartFolder/get	列出智慧型資料夾（請求主體）
POST	/api/v2/smartFolder/create	建立智慧型資料夾
POST	/api/v2/smartFolder/update	更新智慧型資料夾
POST	/api/v2/smartFolder/remove	刪除智慧型資料夾
GET	/api/v2/smartFolder/getItems	取得符合條件的項目
POST	/api/v2/smartFolder/getItems	取得符合條件的項目（請求主體）
GET	/api/v2/smartFolder/getRules	取得可用規則 schema

---

GET /api/v2/smartFolder/get

列出所有智慧型資料夾，或以 ID 篩選。

查詢參數

• id string（可選）— 以 ID 回傳單一智慧型資料夾

• ids string（可選）— 以逗號分隔的智慧型資料夾 ID

回應

{
    "status": "success",
    "data": [
        {
            "id": "LRK3AQGN7VCB1",
            "name": "大尺寸圖片",
            "conditions": [
                {
                    "rules": [
                        { "property": "width", "method": ">", "value": [1920] }
                    ],
                    "match": "AND",
                    "boolean": "TRUE"
                }
            ],
            "description": "",
            "icon": "",
            "iconColor": "blue",
            "children": [],
            "modificationTime": 1700000000000,
            "imageCount": 42
        }
    ]
}

範例

// 列出所有智慧型資料夾
await fetch("http://localhost:41595/api/v2/smartFolder/get").then(r => r.json());

// 以 ID 取得單一智慧型資料夾
await fetch("http://localhost:41595/api/v2/smartFolder/get?id=LRK3AQGN7VCB1").then(r => r.json());

---

POST /api/v2/smartFolder/get

與 GET 相同，但接受 JSON 主體中的篩選參數。

請求主體

• id string（可選）— 智慧型資料夾 ID

• ids string[]（可選）— 智慧型資料夾 ID 陣列

範例

// 以多個 ID 取得智慧型資料夾
await fetch("http://localhost:41595/api/v2/smartFolder/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        ids: ["SMART_FOLDER_ID_1", "SMART_FOLDER_ID_2"]
    })
}).then(r => r.json());

---

POST /api/v2/smartFolder/create

建立新的智慧型資料夾。

請求主體

• name string（必填）— 智慧型資料夾名稱

• conditions Object[]（必填）— 篩選條件（格式請參考下方 conditions 格式說明）

• description string（可選）— 說明

• icon string（可選）— 圖示

• iconColor string（可選）— 圖示顏色。可選值：red、orange、yellow、green、aqua、blue、purple、pink

• parent string（可選）— 父智慧型資料夾 ID。若省略則建立在根層級。

回應

回傳新建立的智慧型資料夾物件。

{
    "status": "success",
    "data": {
        "id": "NEW_SMART_FOLDER_ID",
        "name": "大尺寸圖片",
        "conditions": [
            {
                "rules": [
                    { "property": "width", "method": ">", "value": [1920] }
                ],
                "match": "AND"
            }
        ],
        "description": "",
        "icon": "",
        "iconColor": "",
        "children": [],
        "modificationTime": 1700000000000,
        "imageCount": 150
    }
}

範例

// 建立篩選寬度大於 1920 的 PNG 圖片的智慧型資料夾
await fetch("http://localhost:41595/api/v2/smartFolder/create", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        name: "大尺寸 PNG",
        conditions: [
            {
                "rules": [
                    { "property": "width", "method": ">", "value": [1920] },
                    { "property": "type", "method": "equal", "value": "png" }
                ],
                "match": "AND"
            }
        ],
        iconColor: "blue"
    })
}).then(r => r.json());

---

POST /api/v2/smartFolder/update

更新現有智慧型資料夾的中繼資料。只有您包含的欄位會被修改。

請求主體

• id string（必填）— 要更新的智慧型資料夾 ID

可修改的欄位：

• name string（可選）— 新名稱

• conditions Object[]（可選）— 新篩選條件

• description string（可選）— 新說明

• icon string（可選）— 新圖示

• iconColor string（可選）— 新圖示顏色

回應

回傳更新後的智慧型資料夾物件。

範例

// 更新智慧型資料夾名稱和顏色
await fetch("http://localhost:41595/api/v2/smartFolder/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "LRK3AQGN7VCB1",
        name: "超大尺寸圖片",
        iconColor: "green"
    })
}).then(r => r.json());

// 更新篩選條件
await fetch("http://localhost:41595/api/v2/smartFolder/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "LRK3AQGN7VCB1",
        conditions: [
            {
                "rules": [
                    { "property": "width", "method": ">", "value": [3840] }
                ],
                "match": "AND"
            }
        ]
    })
}).then(r => r.json());

---

POST /api/v2/smartFolder/remove

刪除智慧型資料夾。同時會刪除其所有子智慧型資料夾。

請求主體

• id string（必填）— 要刪除的智慧型資料夾 ID

回應

{
    "status": "success",
    "data": true
}

範例

await fetch("http://localhost:41595/api/v2/smartFolder/remove", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ id: "LRK3AQGN7VCB1" })
}).then(r => r.json());

---

GET /api/v2/smartFolder/getItems

取得符合智慧型資料夾篩選條件的項目。

查詢參數

• smartFolderId string（必填）— 智慧型資料夾 ID

• orderBy string（可選）— 排序欄位

• fields string（可選）— 以逗號分隔的回傳欄位列表

回應

{
    "status": "success",
    "data": [
        {
            "id": "M3QSGJNQTC2DG",
            "name": "wallpaper",
            "ext": "png",
            "width": 3840,
            "height": 2160,
            "tags": ["wallpaper"],
            "folders": []
        }
    ]
}

範例

// 取得智慧型資料夾中的所有項目
await fetch("http://localhost:41595/api/v2/smartFolder/getItems?smartFolderId=LRK3AQGN7VCB1")
    .then(r => r.json());

// 只回傳特定欄位
await fetch("http://localhost:41595/api/v2/smartFolder/getItems?smartFolderId=LRK3AQGN7VCB1&fields=id,name,tags")
    .then(r => r.json());

---

POST /api/v2/smartFolder/getItems

與 GET 相同，但接受 JSON 主體中的參數。

請求主體

• smartFolderId string（必填）— 智慧型資料夾 ID

• orderBy string（可選）— 排序欄位

• fields string[]（可選）— 要回傳的欄位

範例

await fetch("http://localhost:41595/api/v2/smartFolder/getItems", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        smartFolderId: "LRK3AQGN7VCB1",
        fields: ["id", "name", "ext", "width", "height"]
    })
}).then(r => r.json());

---

GET /api/v2/smartFolder/getRules

取得可用的篩選規則 schema。回傳每個 property 支援的 methods、valueType、options 等資訊，讓呼叫者可以動態建構合法的 conditions。

回應

{
    "status": "success",
    "data": {
        "name": {
            "methods": ["contain", "uncontain", "equal", "startWith", "endWith", "empty", "not-empty", "regex"],
            "valueType": "string"
        },
        "width": {
            "methods": ["=", ">=", "<=", ">", "<", "between"],
            "valueType": "number"
        },
        "type": {
            "methods": ["equal", "unequal"],
            "valueType": "string",
            "options": ["jpg", "png", "gif", "svg", "bmp", "webp", "..."]
        }
    }
}

範例

// 取得可用規則，用於動態建構 conditions
await fetch("http://localhost:41595/api/v2/smartFolder/getRules").then(r => r.json());

使用提示： 先呼叫 getRules 取得所有可用的 property 和 method，再根據回傳的 schema 建構 conditions 傳入 create 或 update，可避免無效的篩選條件。

---

Conditions 格式說明

智慧型資料夾的 conditions 是一個條件群組陣列，每個群組包含多條規則：

[
    {
        "rules": [
            { "property": "name", "method": "contain", "value": "cat" },
            { "property": "width", "method": ">", "value": [1920] }
        ],
        "match": "AND",
        "boolean": "TRUE"
    }
]

條件群組屬性

屬性	類型	說明
rules	Object[]	規則陣列
match	string	規則間的邏輯運算。"AND"：全部符合；"OR"：任一符合
boolean	string	群組的包含/排除邏輯。"TRUE"（包含，預設）或 "FALSE"（排除）

規則屬性

屬性	類型	說明
property	string	篩選屬性（如 name、width、type）
method	string	篩選方法（如 contain、>、equal）
value	any	篩選值（格式依屬性和方法而定）

提示： 使用 GET /api/v2/smartFolder/getRules 可查詢所有可用的 property、method 及其對應的 valueType。

---

SmartFolder 屬性

API 回傳的智慧型資料夾包含以下屬性：

屬性	類型	說明
id	string	唯一智慧型資料夾 ID
name	string	名稱
conditions	Object[]	篩選條件
description	string	說明
icon	string	圖示
iconColor	string	圖示顏色
children	Object[]	子智慧型資料夾
modificationTime	integer	最後修改時間戳記
imageCount	integer	符合條件的項目數量