檔案
IIS 系統管理 API 提供一組檔案 API,可直接與檔案系統互動。 這表示 API 可以在本機或遠端使用來部署內容、進行編輯或檢查檔案是否為最新狀態。
/api/files端點會公開電腦上的檔案和目錄的中繼資料和內容。 可透過此 API 取得的檔案僅限於appsettings.json檔案的檔案組態區段中指定的檔案。 查詢 /api/files 端點而不指定目錄將會列出組態中存在的位置。 這些位置代表所有可透過 API 取得之檔案系統路徑的根目錄。 只要檔案路徑具有執行作業所需的宣告,即可使用標準 HTTP 張貼、刪除和修補動詞來建立、刪除及操作檔案。
檔案
{
"name": "iisstart.png",
"id": "{id}",
"type": "file",
"physical_path": "C:\\inetpub\\wwwroot\\iisstart.png",
"exists": "true",
"size": "98757",
"created": "2017-01-09T18:08:33.5130112Z",
"last_modified": "2017-01-09T17:48:13.6180477Z",
"last_access": "2017-01-09T17:48:13.6180477Z",
"e_tag": "1d26aa08c67ed45",
"parent": {
"name": "wwwroot",
"id": "{id}",
"type": "directory",
"physical_path": "C:\\inetpub\\wwwroot"
},
"claims": [
"read",
"write"
]
}
目錄
{
"name": "wwwroot",
"id": "{id}",
"type": "directory",
"physical_path": "C:\\inetpub\\wwwroot",
"exists": "true",
"created": "2017-01-09T18:08:33.1380257Z",
"last_modified": "2017-01-30T17:01:15.2619212Z",
"last_access": "2017-01-30T17:01:15.2619212Z",
"total_files": "7",
"parent": {
"name": "inetpub",
"id": "a-nA1LZCBZ9jIqxr6e2uWg",
"type": "directory",
"physical_path": "C:\\inetpub"
},
"claims": [
"read",
"write"
]
}
/api/webserver/files端點會公開 IIS 所建立的虛擬檔案結構。 此端點下的所有檔案資源都屬於某些網站,而該檔案的路徑相對於其所屬的網站。 這可讓網站被視為檔案系統根目錄,這在網頁伺服器案例中是想要的。 虛擬目錄包含在一般目錄中,以取得網站虛擬檔案階層的完整檢視。
所有網頁伺服器檔案都有 file_info 的參考,這是可從 /api/files 端點取得的檔案中繼資料。
Web 檔案
{
"name": "iisstart.png",
"id": "{id}",
"type": "file",
"path": "/iisstart.png",
"parent": {
"name": "",
"id": "{id}",
"type": "application",
"path": "/"
},
"website": {
"name": "Default Web Site",
"id": "{id}",
"status": "started"
},
"file_info": {
"name": "iisstart.png",
"id": "{id}",
"type": "file",
"physical_path": "C:\\inetpub\\wwwroot\\iisstart.png"
}
}
Web 目錄
{
"name": "imgs",
"id": "{id}",
"type": "directory",
"path": "/imgs",
"parent": {
"name": "",
"id": "{id}",
"type": "application",
"path": "/"
},
"website": {
"name": "Default Web Site",
"id": "{id}",
"status": "started"
},
"file_info": {
"name": "imgs",
"id": "{id}",
"type": "directory",
"physical_path": "C:\\inetpub\\wwwroot\\imgs"
}
}
API 支援透過 /api/files/copy 和 /api/files/move 端點來複製和移動檔案。 複製檔案的程式是透過對描述所需複製作業的 API 執行 POST 要求來執行。
POST
{
"name":"{optional name of the destination file}",
"file": {
"id": "{id property of the file to copy}"
},
"parent": {
"id": "{id property of the directory to copy to}"
}
}
/api/files路由下的資源只包含檔案的中繼資料。 若要操作檔案的內容,一個必須使用 /api/files/content/{id} 路由。 此路由會使用 application/octet-stream 內容類型來傳輸資料。 對檔案的內容 URL 執行 GET 要求,將會復原檔案的原始位元組。 此作業支援 HTTP 範圍要求,以便以區塊方式下載檔案。 對檔案的內容 URL 執行 PUT 要求,將會以要求本文取代檔案的內容。 這項作業支援 HTTP 內容約制要求,以啟用檔案的隨機存取操作。
下載檔案的第 2 個 500 個位元組
GET /api/files/content/{id}
Access-Token: Bearer {Access-Token}
Range: bytes=500-999
編輯 1000 位元組檔案的第 2 個 500 位元組
PUT /api/files/content/{id}
Access-Token: Bearer {Access-Token}
Content-Range: bytes 500-999/1000
Content-Length: 500
檔案可透過 API 的 /api/files/content 端點下載。 此端點的缺點是,因為它位於 API 路由下,因此需要存取權杖。 這表示檔案無法透過瀏覽器下載。 /api/files/download端點可讓您建立暫時下載連結。 這些下載連結是唯一、隨機產生的,而且不需要存取權杖。 產生的下載連結的格式為 /downloads/{random_sequence}。 產生下載連結以指定下載連結的可用時間長度時,可以使用選擇性的存留時間 (ttl) 參數。 預設為五秒鐘。
產生下載時,會在 HTTP 回應的 Location 標頭中傳回下載的連結。
POST
{
"file": {
"id": "{id of the file to download}"
},
"ttl": "10000"
}
檔案 API 可用來管理位於檔案共用上的檔案。 若要啟用這項功能,檔案共用必須允許主體的必要檔案系統許可權,此主體代表 API 執行所在的機器。 例如,假設有位於 \\share\images 的共用內容,而我們想要允許在名為 web-prod-1 的 Web 伺服器上執行的 API 來列舉這些檔案。 若要允許此目的,系統管理員必須修改 \\share\images 目錄的 ACL,以允許 對 web-prod-1 Active Directory 物件的讀取存取。 一旦完成此作業, Web prod-1 電腦上的服務就能夠存取此目錄、讀取檔案,然後透過 API 公開這些檔案。
API 的檔案系統存取僅限於 appsettings 檔案中指定的一組根資料夾,稱為位置。 這些位置會從檔案 API 的觀點顯示為根目錄,但在實體磁片磁碟機上,它們可能是巢狀資料夾、磁片磁碟機的根目錄,甚至是網路共用。 針對每個位置,可獨立控制讀取和寫入存取權。 檔案系統上未落在位置的任何路徑都不會由檔案系統 API 看到。
從 2.2.0 版開始,位置設定可透過 /api/files/locations 端點存取。 此端點會鎖定給 API 擁有 者 使用者群組中的使用者。 這表示需要 Windows 驗證才能存取位置端點。 新增或移除位置將會從 API 新增或移除檔案系統存取權。 此端點支援 GET、PATCH、POST 和 DELETE,以建立、編輯和刪除現有位置。 編輯位置不會影響實體檔案,它只會操作檔案系統的 API 檢視。
預設位置設定
{
"locations": [
{
"alias": "inetpub",
"id": "{id}",
"path": "C:\\inetpub",
"claims": [
"read"
]
}
]
}