synology/references/usage.md

Synology API 工具使用說明

這個目錄放的是 Synology DSM API 相關腳本：

• synology_api.py：共用 API client library
• synology_api_login.py：登入、復用 SID、抓系統資訊

---

1) 先設定環境變數（建議）

可放在 workspace 根目錄 .env：

DS_URL=https://syno.lotimmy.com/
DS_USER=你的帳號
DS_PASSWORD=你的密碼

# 可選：輸出檔案路徑
DS_LOGIN_RESULT=tmp/synology_api_login_result.json
DS_SESSION_FILE=tmp/synology_session.json
DS_SYSINFO_FILE=tmp/synology_system_info.json

---

2) 基本用法

只登入（會先嘗試沿用舊 SID，失效才重登）

python3 synology_api_login.py

登入後抓系統資訊

python3 synology_api_login.py --system-info

顯示人類可讀摘要

python3 synology_api_login.py --system-info --summary

輸出精簡 JSON（適合餵腳本）

python3 synology_api_login.py --system-info --json-compact

---

3) 常用參數

• --url：DSM URL（預設取 DS_URL）
• --user：DSM 帳號（預設取 DS_USER）
• --password：DSM 密碼（預設取 DS_PASSWORD）
• --system-info：抓系統資訊 bundle
• --summary：印出摘要（需搭配 --system-info）
• --json-compact：印出精簡 JSON（需搭配 --system-info）

範例：

python3 synology_api_login.py \
  --url "https://192.168.42.20:5001" \
  --user "admin" \
  --password "******" \
  --system-info --json-compact

---

4) 主要輸出檔

• tmp/synology_api_login_result.json：登入結果（含是否沿用 cached SID）
• tmp/synology_session.json：SID session cache
• tmp/synology_system_info.json：完整系統資訊 API 回傳

---

5) 目前精簡 JSON 會包含

• model
• serial
• ip（優先 eth0）
• dsm_version
• cpu_usage_pct, cpu_clock_mhz
• memory_total_mb, memory_usage_pct
• temperature_c
• volumes
• disk_size_usage（同時有 *_bytes 與 *_gib）
• disk_health（vendor 已去除多餘空白）
• time, uptime

---

6) 執行位置

本 README 的指令都以「目前目錄在 scripts/synology/」為前提。