# Synology API 工具使用說明

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

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

---

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

可放在 workspace 根目錄 `.env`：

```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，失效才重登）

```bash
python3 synology_api_login.py
```

### 登入後抓系統資訊

```bash
python3 synology_api_login.py --system-info
```

### 顯示人類可讀摘要

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

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

```bash
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`）

範例：

```bash
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/`」為前提。