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	利用可能なルールスキーマを取得

---

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

利用可能なフィルタルールスキーマを取得します。各プロパティでサポートされている 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 を呼び出して利用可能なプロパティとメソッドをすべて取得し、返却されたスキーマに基づいて 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 を使用して、利用可能なすべてのプロパティ、メソッド、およびそれに対応する valueType を確認できます。

---

SmartFolder プロパティ

API から返却されるスマートフォルダには以下のプロパティが含まれます：

プロパティ	型	説明
id	string	一意のスマートフォルダ ID
name	string	名前
conditions	Object[]	フィルタ条件
description	string	説明
icon	string	アイコン
iconColor	string	アイコンの色
children	Object[]	子スマートフォルダ
modificationTime	integer	最終更新タイムスタンプ
imageCount	integer	条件に一致するアイテム数