#1f4970
官方英文版鏈接《Synology File Station Official API》
在使用 File Station API 開發自己的應用程序之前，您需要對 API 概念和 API 程序有基本的了解。
本章分以下五個部分解釋如何執行和完成 API 流程：
- API 工作流程：簡要介紹如何使用 File Station API
- 發出請求：詳細說明如何構造 API 請求
- 解析響應：描述如何解析響應數據
- 常見錯誤代碼：列出所有 File Station API 可能返回的所有常見錯誤代碼
- 工作示例：提供請求文件操作的示例
API 工作流程
以下五個步驟且易於遵循的工作流程展示了如何讓您的應用程序與 File Station API 交互。
步驟 1：檢索 API 信息
首先，您的應用程序需要從目標 DiskStation 檢索 API 信息，以了解哪些 API 可在目標 DiskStation 上使用。可以通過 /webapi/query.cgi 使用 SYNO.API.Info API 參數響應中提供的信息包含可用的 API 名稱、API 方法、API 路徑和 API 版本。一旦您掌握了所有信息，您的應用程序就可以向所有可用的 API 發出進一步的請求。
步驟 2：登錄
為了讓您的應用程序與 File Station 交互，您的應用程序需要先使用帳戶和密碼登錄。登錄過程只是使用 login 方法向 SYNO.API.Auth API 發出請求。如果成功，API 會返回一個授權的會話 ID。您應該保留它並將其傳遞給其他 API 請求。
第 3 步：發出 API 請求
成功登錄后，您的應用程序可以開始向所有可用的 File Station API 發出請求。在下一節“發出請求”中，將給出如何形成有效的 API 請求以及如何解碼響應信息的說明。
第 4 步：注銷
完成上述步驟后，您的應用程序可以通過 注銷 方法。
發出請求
有五個基本元素可用於構建對任何 API 的有效請求。
- API name: API請求的名字
- version: API請求的版本
- path: API的路徑。可以通過請求 SYNO.API.Info 來檢索路徑信息
- method: API請求的方法
- _sid: 授權會話 ID。每個 API 請求都應該通過它，它是從 /webapi/auth.cgi ，通過帶有 _sid 參數的 HTTP/HTTPS GET/POST 方法。否則，如果你在 id HTTP/HTTPS header的cookie值，該參數可以忽略。
請求的語法如下：
GET /webapi/<CGI_PATH>?api=<API_NAME>&version=<VERSION>&method=<METHOD>[&<PARAMS>][&_sid=<SID>]
這里 <參數> 表示請求方法的參數，是可選的。請注意，所有參數都需要轉義。逗號“，”替換為斜杠“\”，斜杠“\”替換為雙斜杠“\\”，因為逗號“，”用於分隔參數中的多個元素。密碼相關參數不需要轉義，包括 passwd 或密碼參數。
請看下面的例子。如果您想在 查詢 地址為 http://myds.com:port （HTTP 和 HTTPS 的默認端口分別為 5000 或 5001）對於所有可用 API 方法的列表，對應的參數是：
- API name: SYNO.API.Info
- version: 1
- path: query.cgi
- method: query
- _sid: query=all
請求將如下所示：
http://myds.com:port/webapi/query.cgi?api=SYNO.API.Info&version=1&method=query&query=all
請注意，可以通過向 SYNO.API.Info 發送請求來獲取 API 的路徑和支持的版本信息。 SYNO.API.Info 的位置是固定的，因此您始終可以使用 /webapi/query.cgi 請求 SYNO.API.Info 。
解析響應
所有 API 響應都以 JSON 格式編碼，JSON 響應包含以下元素：
| 鍵 |
值 |
描述 |
| success |
true/false |
“true”：請求成功完成； “false”：請求失敗並返回錯誤數據。 |
| data |
<JSON 樣式 Object> |
數據對象包含每個方法中描述的所有響應信息。 |
| error |
<JSON 樣式 Object> |
數據對象包含請求失敗時的錯誤信息。下表描述了基本元素。 |
下面描述錯誤元素中錯誤信息的格式。
| 鍵 |
值 |
描述 |
| code |
錯誤 代碼。 |
請求失敗時返回錯誤碼錯誤碼有兩種：一種是所有 API 共享的通用錯誤碼；另一個是特定的 API 錯誤代碼（在相應的 API 規范中描述）。 |
| errors |
<JSON 樣式 數組> |
該數組包含每個文件的詳細錯誤信息。錯誤中的每個元素都是一個 JSON 樣式的對象，其中包含錯誤代碼和其他信息，例如文件路徑或名稱。 注意：當沒有詳細信息時，此錯誤元素將不會響應。 |
示例 1
在沒有方法參數的情況下響應無效請求以獲取 File Station 的信息。
請求：
http://myds.com:port/webapi/entryFilStation/info.cgi?api=SYNO.FileStation.Info&version=2&method=get
失敗響應：
{
"success": false,
"error": {
"code": 101
}
}
示例 2
使用非法路徑響應無效請求以創建文件夾。
請求：
http://myds.com:port/webapi/FilStation/info.cgi?api=SYNO.FileStation.CreateFolder&method=create&version=1&folder_path=%2Ftest&name=%3A
失敗響應：
{
"success": false,
"error": {
"code": 1100,
"errors": [
{
"code": 418,
"path": "/test/:"
}
]
}
}
示例3
響應從 File Station 獲取信息的成功請求。
請求：
http://myds.com:port/webapi/FilStation/info.cgi?api=SYNO.FileStation.Info&version=2&method=get
成功響應：
{
"success": true,
"data": {
"is_manager": true,
"hostname": "DS",
"support_sharing": true,
"support_virtual": "cifs,iso"
}
}
請注意，為了清楚地演示示例，以下部分中給出的響應示例中僅包含數據對象。
常見錯誤代碼
以下代碼是所有 WebAPI 的參數錯誤或登錄失敗的常見錯誤代碼。
| 代碼 |
說明 |
| 100 |
未知錯誤 |
| 101 |
API、方法或版本沒有參數 |
| 102 |
請求的 API 不存在 |
| 103 |
請求的方法不存在 |
| 104 |
請求的版本不支持該功能 |
| 105 |
登錄的會話沒有權限 |
| 106 |
會話超時 |
| 107 |
會話因重復登錄而中斷 |
| 119 |
SID 未找到 |
下面列出的代碼是所有 File Station API 的文件操作的常見錯誤代碼。
| 代碼 |
說明 |
| 400 |
文件操作參數無效 |
| 401 |
未知錯誤 |
| 402 |
系統太忙 |
| 403 |
無效用戶執行此文件操作 |
| 404 |
無效組執行此文件操作 |
| 405 |
無效用戶和組執行此文件操作 |
| 406 |
無法 從帳戶服務器獲取用戶/組信息 |
| 407 |
不允許操作 |
| 408 |
沒有這樣的文件或目錄 |
| 409 |
不支持的文件系統 |
| 410 |
無法連接基於 Internet 的文件系統（例如，CIFS） |
| 411 |
只讀文件系統 |
| 412 |
文件名太長在非加密文件系統中 |
| 413 |
在加密文件系統中文件名太長 |
| 414 |
文件已存在 |
| 415 |
磁盤配額超出 |
| 416 |
設備上沒有剩余空間 |
| 417 |
輸入/輸出錯誤 |
| 418 |
非法名稱或路徑 |
| 419 |
非法文件名 |
| 420 |
FAT 上的非法文件名文件系統 |
| 421 |
設備或資源繁忙 |
| 599 |
文件操作沒有此類任務 |
工作示例
以下演示了從 DiskStation 請求文件操作的工作示例。要實施此示例，只需將示例中使用的 DiskStation 地址 (myds.com:port) 替換為您的 DiskStation 地址並將 URL 粘貼到瀏覽器。然后 JSON 響應將顯示在響應頁面中。
第 1 步：獲取 API 信息
為了發出 API 請求，您應該首先 /webapi/query.cgi 以獲取用於登錄的 SYNO.API.Auth API 信息和用於文件操作的 FileStation API 信息.
請求：
http://myds.com:port/webapi/query.cgi?api=SYNO.API.Info&version=1&method=query&
query=SYNO.API.Auth,SYNO.FileStation
響應：
{
"data": {
"SYNO.API.Auth": {
"path": "auth.cgi",
"minVersion": 1,
"maxVersion": 3
},
"SYNO.FileStation.List": {
"path": "FileStation/file_share.cgi",
"minVersion": 1,
"maxVersion": 1
}
},
"success": true
}
第 2 步：登錄
在返回 SYNO.API.Auth 路徑和支持的版本信息后，您可以通過請求位於 /webapi/auth.cgi 的 SYNO.API.Auth API 版本 3 來登錄 FileStation 會話 。
請求：
http://myds.com:port/webapi/auth.cgi?api=SYNO.API.Auth&version=3&method=login&account=admin&
passwd=12345&session=FileStation&format=cookie
響應：
{
"data": {
"sid": "ohOCjwhHhwghw"
},
"success": true
}
第 3 步：請求 File Station API
會話登錄后，您可以繼續調用 SYNO.FileStation.List 中列出共享文件夾的方法。在Step 1的響應中提供了cgi路徑和版本，可以通過排除 offset 和 limit 參數來請求所有任務的列表。
請求：
http://myds.com:port/webapi/FileStation/file_share.cgi?api=SYNO.FileStation.List&version=1&method=list_share
響應：
{
"data": {
"offset": 0,
"shares": [
{
"isdir": true,
"name": "video",
"path": "/video"
},
{
"isdir": true,
"name": "photo",
"path": "/photo"
}
],
"total": 2
},
"success": true
}
列表中可以看出 File Station 中有兩個共享文件夾。假設您對共享文件夾“照片”感興趣並想了解有關它的更多詳細信息，您可以向 getinfo 方法。在此請求中，您需要添加參數 additional=real_path,owner,time 用於請求詳細對象並在響應中傳輸它們的方法。
請求：
http://myds.com:5000/webapi/FileStation/file_share.cgi?api=SYNO.FileStation.List&version=1& method=getinfo&path=%2Fphoto&additional=real_path,owner,time,perm
響應：
{
"data": {
"files": [
{
"additional": {
"owner": {
"gid": 100,
"group": "users",
"uid": 1024,
"user": "admin"
},
"real_path": "/volume1/photo",
"time": {
"atime": 1371630215,
"crtime": 1352168821,
"ctime": 1368769689,
"mtime": 1368769689
}
},
"isdir": true,
"name": "photo",
"path": "/photo"
}
]
},
"success": true
}
第 4 步：注銷
完成該過程后，您應該注銷當前會話。會話將通過調用 注銷 SYNO.API.Auth 中的方法。如果要注銷特定會話，可以通過設置 _sid 參數。
示例：
http://myds.com:5000/webapi/auth.cgi?api=SYNO.API.Auth&version=1&method=logout&session=FileStation