Tag

Tag API 允許您列出、重新命名及合併 Eagle 資源庫中的標籤。

端點概覽

方法	端點	說明
GET	/api/v2/tag/get	列出所有標籤
POST	/api/v2/tag/get	列出標籤（請求主體）
GET	/api/v2/tag/getRecentTags	取得最近使用的標籤
GET	/api/v2/tag/getStarredTags	取得已加星號的標籤
POST	/api/v2/tag/update	重新命名標籤
POST	/api/v2/tag/merge	合併兩個標籤

---

GET /api/v2/tag/get

列出資源庫中的所有標籤。回傳分頁結果。

查詢參數

• name string（可選）— 以名稱篩選標籤（子字串匹配）

• offset integer（可選）— 分頁偏移量，預設 0

• limit integer（可選）— 分頁限制，預設 50，最大 1000

回應

{
    "status": "success",
    "data": {
        "data": [
            {
                "name": "design",
                "count": 150,
                "color": "",
                "groups": ["GROUP_ID_1"],
                "pinyin": "design"
            },
            {
                "name": "photography",
                "count": 89,
                "color": "",
                "groups": [],
                "pinyin": "photography"
            }
        ],
        "total": 340,
        "offset": 0,
        "limit": 50
    }
}

範例

// 列出所有標籤（前 50 個）
await fetch("http://localhost:41595/api/v2/tag/get").then(r => r.json());

// 以名稱篩選標籤
await fetch("http://localhost:41595/api/v2/tag/get?name=design").then(r => r.json());

// 分頁瀏覽標籤
await fetch("http://localhost:41595/api/v2/tag/get?offset=50&limit=100").then(r => r.json());

---

POST /api/v2/tag/get

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

請求主體

• name string（可選）— 以名稱篩選標籤（子字串匹配）

• offset integer（可選）— 分頁偏移量，預設 0

• limit integer（可選）— 分頁限制，預設 50，最大 1000

範例

await fetch("http://localhost:41595/api/v2/tag/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ name: "design", limit: 100 })
}).then(r => r.json());

---

GET /api/v2/tag/getRecentTags

取得最近使用的標籤。回傳分頁結果。

查詢參數

• offset integer（可選）— 分頁偏移量，預設 0

• limit integer（可選）— 分頁限制，預設 50，最大 1000

回應

{
    "status": "success",
    "data": {
        "data": [
            {
                "name": "ui-design",
                "count": 45,
                "color": "",
                "groups": [],
                "pinyin": "ui-design"
            }
        ],
        "total": 12,
        "offset": 0,
        "limit": 50
    }
}

範例

await fetch("http://localhost:41595/api/v2/tag/getRecentTags").then(r => r.json());

---

GET /api/v2/tag/getStarredTags

取得已加星號（釘選）的標籤。回傳分頁結果。

查詢參數

• offset integer（可選）— 分頁偏移量，預設 0

• limit integer（可選）— 分頁限制，預設 50，最大 1000

回應

與 /api/v2/tag/getRecentTags 格式相同。

範例

await fetch("http://localhost:41595/api/v2/tag/getStarredTags").then(r => r.json());

---

POST /api/v2/tag/update

重新命名現有標籤。所有使用此標籤的項目都會自動更新。

請求主體

• originalName string（必填）— 目前的標籤名稱

• name string（必填）— 新的標籤名稱

回應

回傳更新後的標籤物件。

{
    "status": "success",
    "data": {
        "name": "new-tag-name",
        "count": 45,
        "color": "",
        "groups": [],
        "pinyin": "new-tag-name"
    }
}

範例

await fetch("http://localhost:41595/api/v2/tag/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        originalName: "old-tag-name",
        name: "new-tag-name"
    })
}).then(r => r.json());

---

POST /api/v2/tag/merge

將來源標籤合併到目標標籤。所有擁有來源標籤的項目會被替換為目標標籤。合併後來源標籤會被移除。

請求主體

• source string（必填）— 要合併的來源標籤名稱（將被移除）

• target string（必填）— 要合併至的目標標籤名稱（將被保留）

回應

{
    "status": "success",
    "data": {
        "affectedItems": 25,
        "sourceRemoved": true
    }
}

範例

// 將 "photograph" 合併到 "photography"
await fetch("http://localhost:41595/api/v2/tag/merge", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        source: "photograph",
        target: "photography"
    })
}).then(r => r.json());

---

Tag 屬性

API 回傳的標籤包含以下屬性：

屬性	類型	說明
name	string	標籤名稱
count	integer	使用此標籤的項目數量
color	string	標籤顏色（未設定時為空字串）
groups	string[]	標籤群組 ID 陣列
pinyin	string	名稱的拼音表示