使用 API 串接 Synology NAS 服務

---

---

最近公司的系統為了因應大量的資料儲存，選擇改為把資料存放在NAS，所以就來研究一下如何透過API串接此服務。

基本上如何使用都可以參考官方文檔 Synology_File_Station_API_Guide，此篇主要紀錄幾個使用過的 API 與遇到的問題。

要使用此服務的各項 API 基本上都得先登入取得權限。而各個參數都是以查詢字串的方式夾帶。

API Request:

Get
http://myds.com:port/webapi/auth.cgi?api=SYNO.API.Auth&version=3&method=login&account=admin&passwd=12345&session=FileStation&format=cookie

網址：http://{nasurl}:5000/webapi/auth.cgi
http的port為5000，https為5001

查詢字串為:

api=SYNO.API.Auth

version=3

method=login

account=your account

passwd=your passwd

session=FileStation

format=cookie

Response:

{
    "data": {
        "did": "WeoBfHknZ4EllXoN4Jjds8ukcgyWyVJfQvoz60xTTpzMSpEaD8GU_yvrvjxK10h1Z4eMUhaxtyH5OphCCGl5Hw",
        "sid": "2ZLVB8UbL6EHnkI4uCO730lqNgJyzjBfhDcodeqNETcG_pMHr5yjt-gTYI0OtpzbmXAxlmZMXi3PyHkEyZHI0E"
    },
    "success": true
}

did 為 nas 服務的 ID，sid 為登入後取得的權限證明，之後呼叫任何 API 可以選擇以 cookie 或是查詢字串的方式攜帶。

此篇都使以查詢字串的方式攜帶 sid，參數為 _sid=sid。

API Request:

Get
http://myds.com:5000/webapi/auth.cgi?api=SYNO.API.Auth&version=1&method=logout&session=FileStation

查詢字串為:

api=SYNO.API.Auth

version=1

method=logout

session=FileStation

_sid=sid

Response:

{
    "success": true
}

經測試 sid 的權限，時效蠻久的，所以並不需要頻繁的登入與登出，目前是採用每次與NAS操作時，先判斷 sid 是否還可以使用，若不行再執行登入的動作取得新的 sid。

API Request:

Get
http://myds.com:5000/webapi/entry.cgi?api=SYNO.FileStation.CreateFolder&version=2&method=create&folder_path=%5B%22%2Fvideo%22%5D&name=%5B%22test%22%5D

查詢字串為:

api=SYNO.FileStation.CreateFolder

version=2

method=create

folder_path=/path

name=folderName

_sid=sid

Response:

{
    "data": {
        "folders": [
            {
                "isdir": true,
                "name": "XDS",
                "path": "/SPM/XDS"
            }
        ]
    },
    "success": true
}

API Request:

Get
http://myds.com:5000/webapi/entry.cgi?api=SYNO.FileStation.Delete&version=2&method=start&path=%22%2Fvideo%2Fdel_folder%22

查詢字串為:

api=SYNO.FileStation.Delete

version=2

method=start

path=/filePath

name=folderName

_sid=sid

Response:

{
    "data": {
        "taskid": "FileStation_657A5A3DF1C925ED"
    },
    "success": true
}

執行刪除會回傳一個 taskid，這代表是一個執行刪除的動作。若要查詢是否刪除成功則需呼叫另一個 API。

API Request:

Get
http://myds.com:5000/webapi/entry.cgi?api=SYNO.FileStation.Delete&version=2&method=status&taskid=%22FileStation_51CEC9C979340E5A%22

查詢字串為:

api=SYNO.FileStation.Delete

version=2

method=status

taskid=FileStation_657A5A483B021703

_sid=sid

Response:

{
    "data": {
        "finished": true,
        "path": "",
        "processed_num": 0,
        "processing_path": "",
        "progress": 1,
        "total": -1
    },
    "success": true
}

即可確認此檔案或資料夾是否刪除成功。

API Request:

Post
http://myds.com:5000/webapi/entry.cgi?api=SYNO.FileStation.Upload&version=2&method=upload&path=/SPM/XD&create_parents=true&_sid=AgQzS8bUN7bJcfwfwHj4n2ZT_pjmC5PQAiKV_Xt27AgTO8B9uySZqhK9uQg8UosfMvBLUKrtYqrZtQKp1fJVqU

查詢字串為:

api=SYNO.FileStation.Upload

version=2

method=upload

path=/folderPath

create_parents=true

_sid=sid

Body 的部分需使用 form-data 的格式:

Response:

{
  "data": {
    "blSkip": false,
    "file": "unnamed.png",
    "pid": 30385,
    "progress": 1
  },
  "success": true
}

檔案上傳的部分官方文檔寫的有看沒有懂，不太清楚參數到底是得放在查詢字串裡還是 orm-data 裡，結果兩邊都放檔案才上傳成功...。

API Request:

Get
http://myds.com:5000/webapi/entry.cgi?api=SYNO.FileStation.Download&version=2&method=download&path=%5B%22%2Ftest%2FITEMA_20445972-0.mp3%22%5D&mode=%22open%22

查詢字串為:

api=SYNO.FileStation.Download

version=2

method=download

path=/filePath

mode=open or download

使用open為開啟檔案或資料夾，HTTP標頭的 Content-Type 可設置為根據檔案對應的 MIME 類型。
使用download 為下載檔案或資料夾，HTTP標頭的 Content-Type 設置為 application/octet-stream，而 Content-Disposition 設置為 attachment，這樣可以告訴瀏覽器將其視為附件並提示下載。

_sid=sid

需要注意的為檔案上傳的部分，參數使用查詢字串攜帶的同時，也需使用 form-data 傳遞才能成功，這個地方嘗試了許久...。這次算是第一次串接 NAS 服務，平常都是提供 API 給人串接，經歷過這次體會到 API 文件書一定要寫好，不然遇到問題一直靠通靈真的是頗麻煩。

Web

---

---