使用 Unity Catalog 磁碟區的 Files API

使用 Files API 來依路徑讀取、寫入、列出及刪除檔案與目錄。 它適用於 Unity 目錄卷中的檔案，你可用其絕對卷路徑來參照，例如 /Volumes/<catalog>/<schema>/<volume>/<path>。 Files API 3.0 的請求會使用 /api/3.0/fs 端點前綴，並前往你工作區的 區域主機名稱。 關於每個操作、參數和標頭，請參考 Files API 3.0 參考。

使用 Files API 可能會產生 Azure Databricks 資料傳輸費用。

將請求傳送至區域主機名稱

將 Send Files API 3.0 請求發送到請求使用者所屬工作區的區域主機名稱。 區域主機名稱格式如下：

<workspace-id>.storage.<workspace-region>.<databricks-domain>

例如： 1234567890123456.storage.westus.azuredatabricks.net 。

要找到你的工作區 ID 和區域，請使用帳號主控台。 請參閱 工作區實例名稱、URL 和識別碼。 你也可以在部署網址中找到工作區 ID：在 https://<databricks-instance>/?o=1234567890123456 中，o= 之後的數字是工作區 ID。 工作區介面會顯示工作區名稱下方的區域。

設定網路連線能力

Files API 3.0 需要從你的網路連線到 Azure Databricks，以及從 Azure Databricks 連線到你的儲存體。

從你的網路到 Azure Databricks

如果你允許公共網際網路存取工作區，但用防火牆限制，請將你所在區域的控制平面 IP 範圍加入允許清單。

將 IP 納入控制平面 IP，包括預設儲存和網頁應用程式。 請參閱輸入至 Azure Databricks 控制平面。

如果你不允許 Azure Databricks 存取網際網路，且透過前端私有連結連線，請為效能密集型服務建立第二個前端私有連結。 請參見 「配置入站專用連結」以獲取效能密集型服務。

從 Azure Databricks 到您的儲存體

如果你允許公開存取你的儲存體但套用網路限制，對於區域內儲存，請將你的儲存帳號加入 Azure 網路安全周邊（NSP），然後將AzureDatabricksServerless服務標籤加入允許清單。 網路安全邊界必須維持在過渡模式。 否則，將 Azure Databricks 的輸出 IP 加入允許清單。

如果你不允許公開存取你的儲存空間，請設定一個私人連結到你的 Azure 儲存空間。 參見 設定與Azure資源的私人連線。

使用多部分上傳來上傳大型檔案

單一上傳請求可接受最高 5000 MiB 的檔案。 若要上傳較大的檔案，或上傳開始時大小未知的檔案，請使用 multipart upload：你將檔案分段上傳，Azure Databricks 會將它們組合成一個檔案。

零件編號範圍從1到10000不等。 除了最後一個部分外，每個部分必須至少有 5 MiB，每個部分最多可達 4000 MiB。 Azure Databricks 會依零件號遞增順序組裝零件。 對於每個參數，請參見 上傳檔案 及 對檔案執行動作。

多部分上傳範例

以下範例將檔案分為兩部分上傳。

要開始上傳會話，請先啟動上傳。 回應包含用於識別工作階段的 upload_id：

POST /api/3.0/fs/files/Volumes/c/s/v/file?action=initiate-upload

200 OK
Content-Type: application/json
{
  "upload_id": "dvOR6FE39mNb"
}

要上傳第一部分，請使用 upload_id 和 part_number 傳送其內容。 回應內容包括該部分的 ETag

PUT /api/3.0/fs/files/Volumes/c/s/v/file?upload_id=dvOR6FE39mNb&part_number=1
Content-Length: 268435456
Content-Type: application/octet-stream
<binary data>

200 OK
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

若要上傳第二部分，請使用下一個 part_number重複提出請求：

PUT /api/3.0/fs/files/Volumes/c/s/v/file?upload_id=dvOR6FE39mNb&part_number=2
Content-Length: 268435456
Content-Type: application/octet-stream
<binary data>

200 OK
ETag: "954fb694be262821177cfbc47f9d4a0aa06c349b"

最後，請以一個列出所有零件及其儲存的 ETag 的正文完成上傳：

POST /api/3.0/fs/files/Volumes/c/s/v/file?action=complete-upload&upload_id=dvOR6FE39mNb
Content-Type: application/json
{
  "parts": [
    { "part_number": 1, "etag": "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"" },
    { "part_number": 2, "etag": "\"954fb694be262821177cfbc47f9d4a0aa06c349b\"" }
  ]
}

200 OK
ETag: "b3f1c2a94d6e7085f2a1c0b9e8d7654321fedcba"

在這個回應中，ETag 屬於整個已組合的檔案，而非其中一部分。 你可以在後續的 條件請求中使用它，例如只有在該檔案自上傳後未曾改變時才覆蓋該檔案。

若要取消上傳而非完成，請傳送 abort-upload 動作，並附上 upload_id：

POST /api/3.0/fs/files/Volumes/c/s/v/file?action=abort-upload&upload_id=dvOR6FE39mNb

200 OK

使用範圍請求下載大型檔案

使用範圍請求以多個較小的請求下載大型檔案，或恢復中斷的下載。

要求範圍

在 Range 標頭中傳送你想要的第一個和最後一個位元組的從 0 開始位置。 此範圍包含這兩個位置選項。 例如，bytes=0-1048575 請求一個 10 MiB 檔案的前 1 MiB：

GET /api/3.0/fs/files/Volumes/main/default/my-volume/large-file.bin
Range: bytes=0-1048575

206 Partial Content
Accept-Ranges: bytes
Content-Range: bytes 0-1048575/10485760
Content-Length: 1048576
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
<binary data>

回應只 206 Partial Content 包含請求的位元組，並 Content-Range 顯示包含哪些位元組及檔案的總大小。 要讀到檔案末尾，請省略最後一個位置，如 bytes=1048576-。 如果最後一個位置在檔案末尾之後，回應會包含直到檔案結尾為止的位元組。 關於其他 Range 語法，請參見 「下載檔案」。

HEAD帶有Range標頭的請求會回傳與匹配GET請求相同的狀態與標頭，但不會包含主體。

恢復中斷的下載。

要繼續下載，請請求剩餘的位元組，範圍從你沒收到的第一個位元組開始。 另外，請將第一個回覆中的 If-Match 與 ETag 一併傳送，避免將兩個版本的位元組合併：

GET /api/3.0/fs/files/Volumes/main/default/my-volume/large-file.bin
Range: bytes=1048576-
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

206 Partial Content
Accept-Ranges: bytes
Content-Range: bytes 1048576-10485759/10485760
Content-Length: 9437184
<binary data>

如果檔案有變動，伺服器會回傳 412 Precondition Failed，你必須重新開始下載。

使用條件請求

條件請求只有在檔案處於你預期的狀態時才會生效。 使用條件請求以避免重複下載，防止同時寫入者互相覆寫，並安全地建立或刪除檔案。 檔案 API 3.0 支援 RFC 9110 中的四個標準 HTTP 條件標頭：

當條件未被滿足時，伺服器不會執行該操作，並回傳以下其中一種狀態：

• 304 Not Modified，當使用 If-None-Match 或 If-Modified-Since 的 GET 或 HEAD 請求失敗時。 你快取的副本仍然有效。
• 412 Precondition Failed，當其他條件不成立時。

驗證者：ETag 與 Last-Modified

條件標頭會比較你提供的值與檔案中的驗證器之一。 檔案 API 會在 GET 和 HEAD 上將兩個驗證器作為回應標頭傳回：

• ETag：檔案內容的不透明識別碼，同樣在 PUT 以及多段 complete-upload 回應中回傳。 請完全按照傳回時的原樣儲存，包括周圍的引號，不要解析或構造。
• Last-Modified：檔案最後修改時間，作為 HTTP 日期。 它的精度是一秒，因此If-Modified-SinceIf-Unmodified-Since無法在同一秒內偵測多次變更。 對於並行控制，請使用 ETag 搭配 If-Match 或 If-None-Match。

條件讀取

最常見的條件讀取是快取重新驗證。 傳送 If-Modified-Since，並附上你快取副本的 If-None-Match；或傳送 ETag，並附上你上次擷取它的時間。 如果檔案未被更改，伺服器會返回 304 Not Modified，且沒有回應本文。 否則，會回傳 200 OK，並帶有新內容：

GET /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

304 Not Modified

If-Match 和 If-Unmodified-Since 則相反：伺服器只有在檔案未變更時才回傳該檔案，否則回傳 412。 一次讀取最多可包含兩個條件標頭，其優先順序遵循 RFC 9110。

條件寫入

在 PUT上，使用 If-None-Match 和 If-Match 以避免覆蓋你沒看到的變更，也稱為 遺失更新問題：

• If-None-Match: * 只有當路徑上沒有檔案時才會上傳檔案。 否則，請求會回傳 412 Precondition Failed。
• If-Match: <etag> 只有當檔案目前的 ETag 和你提供的值相符時，才會上傳該檔案。 否則，請求會回傳 412 Precondition Failed，或 404 當路徑上沒有檔案時。

若要建立檔案，前提是該檔案尚未存在，請傳入 If-None-Match: *：

PUT /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-None-Match: *
Content-Type: application/octet-stream
<binary data>

200 OK

如果檔案仍是你最後取得的版本，才要覆寫，請將其 ETag 與 If-Match 一併傳送。

PUT /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Content-Type: application/octet-stream
<binary data>

200 OK

對於 多部分上傳，請在 initiate-upload 呼叫時傳送條件標頭。 檔案 API 會在上傳完成時評估它，因此該條件會套用在組合後的檔案上。 關於每個呼叫所支援的標頭表單，請參見 上傳檔案 及 對檔案執行動作。

條件刪除

即使檔案不存在，單純執行 DELETE 也會成功，因此無法判斷你是否移除了原本想要的版本。 若要讓刪除附帶條件，請發送 If-Match：

• If-Match: <etag> 只有當檔案目前的 ETag 與你提供的值相符時，才會刪除該檔案。 如果有人在你取得檔案後更改了檔案，請求會回傳 412 Precondition Failed。 若檔案不復存在，則返回 404。
• If-Match: * 只有在檔案存在時才會刪除，沒有時則回傳 404 。

DELETE /api/3.0/fs/files/Volumes/main/default/reports/report.csv
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

204 No Content

檔案 API 版本

Files API 2.0 會向你的工作區主機名稱發送請求，並使用 /api/2.0/fs 作為端點前綴。 它不支援多段上傳，且其唯一的條件標頭是用於下載的 If-Unmodified-Since。 請參閱 Files API 2.0 參考資料。

要將程式碼從 Files API 2.0 遷移到 3.0，請進行以下變更：

• 向帶有端點前綴的/api/3.0/fs發送請求，並設定網路連線。
• 每次上傳都要把 Content-Length 標頭送出去。 如果你事先不知道檔案大小，可以用 multipart 上傳。
• 成功上傳後，應顯示 200 OK，而不是 204 No Content。
• 當你刪除不存在的檔案時，請期待 204 No Content，而不是 404 Not Found。 參見 有條件刪除。