Fabric Apps Storage 是建立在 OneLake 上,讓你可以將文件、圖片和附件加入應用程式。 用 Rayfin 定義資料夾和存取規則,然後用客戶端 SDK 上傳、列出、下載和刪除檔案。 在你的資料模型中保留結構化應用程式資料。
檔案操作在開發期間及部署後皆使用 Fabric 儲存;沒有本地儲存模擬器。
Prerequisites
- 需要 Fabric Apps 專案以及 Node.js 20 或更新版本。
- 已為你的租戶啟用 Fabric 應用程式。
- 已啟用 使用者可以透過 Fabric 以外的應用程式存取儲存在 OneLake 中的資料 Fabric 租戶設定。 請參見 啟用 OneLake 存取。
- 存取已指定支援 Fabric 容量的 Fabric 工作區。 Power BI Pro 工作區不支援儲存功能。
- 部署應用程式並套用其儲存設定的權限。
- 一個已設定的資料 服務,包括
services.data.dialect。 - 為應用程式設定的 Fabric 驗證,並為使用者建立了登入流程。
啟用 OneLake 存取權限
檔案上傳與下載依賴 OneLake 存取權限。 請你的 Fabric 管理員啟用 使用者可以使用 Fabric 外部的應用程式存取儲存在 OneLake 中的資料 租用戶設定。 預設是整個組織啟用的。 Fabric Apps Storage 需要啟用此設定。 這個設定一般控制 Fabric 外部應用程式的存取,而不只是你的應用程式。 你還需要定義資料夾權限,來控制每位應用程式使用者能存取哪些檔案。 欲了解更多資訊,請參閱 OneLake 租戶設定。
啟用儲存
使用 GitHub Copilot 或其他可存取您的專案和終端機的程式代理程式來配置儲存空間。 例如,使用以下提示:
Use Rayfin Storage to add a documents folder to my Fabric app.
Allow signed-in users to manage their own PDF files, up to 10 MiB each.
Use the installed Rayfin documentation and project guidance to configure and
register the folder, and connect storage to my existing authenticated client.
Preserve my existing services and folders. Show me the changes before deploying,
and ask before making any potentially destructive changes.
檢視產生的設定、資料夾權限和客戶端變更。 Storage 需要啟用並設定 Data service。 每個資料夾都需要一個已驗證的權限規則。 資料夾權限控制檔案存取;路徑僅組織內容。 欲了解更多權限資訊,請參閱 定義資料權限。
套用設定
從專案根目錄部署你的應用程式:
npx rayfin up
完整部署會在啟用儲存時套用已註冊的資料夾。 使用資料夾前,請先檢查部署輸出是否有儲存警告。 若要重試失敗的儲存步驟或僅對現有部署套用資料夾變更,請執行:
npx rayfin up storage apply
成功完整部署後,你不需要執行 storage-only 指令。
針對遠端儲存開發
開始你的開發工作階段:
npx rayfin dev
透過使用預設的 Fabric 提供者,這個指令會將啟用的儲存宣告套用到 Fabric 中的開發應用程式。 你的前端是本地運作,但檔案操作是讀取和寫入遠端檔案。 使用開發應用程式,測試時避免使用生產資料。
若要重試目前使用中的開發部署的儲存設定,請執行:
npx rayfin dev storage apply
在使用這個僅儲存指令之前,先啟動一個完整 rayfin dev 工作階段。
重試指令使用目前啟用中的部署,且不接受 --workspace 或 --workspace-id。
Docker 提供者不支援儲存功能。
設定用戶端
將儲存空間連接到你應用程式現有的客戶端,並保留其設定與登入流程。 設定提示可以幫助你為你的專案設定用戶端。 登入與儲存呼叫必須使用同一個用戶端會話。 建立客戶端並不會讓使用者登入。
處理檔案
以下範例使用你已設定、已登入的 client 實例和 documents 資料夾。
物件路徑是相對於該資料夾的。
在路徑段之間使用 / ,並包含上傳、下載及刪除操作的檔名。
不要使用前導或尾隨的 /、反斜線、空白區段、. 區段或 .. 區段。
上傳檔案
傳遞使用者選擇的檔案瀏覽器 File :
async function uploadDocument(file: File) {
return client.storage.documents.upload('reports/quarterly-report.pdf', file, {
contentType: 'application/pdf',
contentDisposition: 'attachment; filename="quarterly-report.pdf"',
});
}
上傳完成後,使用相同的路徑下載或刪除檔案。
再次上傳到相同路徑會依照資料夾的 onConflict 設定進行。
可選 contentDisposition 值則儲存描述檔案應如何呈現的元資料,例如帶有建議檔名的附件。
清單檔
從資料夾根目錄列表,或提供目錄路徑以縮小搜尋範圍:
const firstPage = await client.storage.documents.list('reports', {
limit: 20,
});
for (const item of firstPage.items) {
console.log(item.path, item.size);
}
if (firstPage.continuation) {
const nextPage = await client.storage.documents.list('reports', {
limit: 20,
continuation: firstPage.continuation,
});
console.log(nextPage.items);
}
不帶目錄路徑呼叫 list(),即可從資料夾根目錄列出內容。
使用回傳的接續權杖來取得更多頁面。
儲存 API 可以在清單結果中包含處於 Deleting 狀態的檔案。
你無法在那種狀態下上傳或下載檔案。
如果刪除沒完成,請再試一次刪除檔案。
下載檔案
使用你上傳時提供的相同相對路徑:
const result = await client.storage.documents.download(
'reports/quarterly-report.pdf'
);
const file = await new Response(result.stream, {
headers: result.contentType
? { 'Content-Type': result.contentType }
: undefined,
}).blob();
在你應用程式的顯示或下載流程中,利用結果 Blob 來處理受限檔案。
此轉換會將整個檔案緩衝在記憶體中。
對於大型檔案,建議逐步消耗 result.stream 。
如果你使用 URL.createObjectURL 建立物件 URL,當應用程式不再需要時,請撤銷該 URL。
刪除檔案
依其相對路徑刪除該檔案:
await client.storage.documents.delete('reports/quarterly-report.pdf');
若上傳或刪除操作中斷,可能會暫時阻擋同一路徑上的另一操作。 等一等再試。 在某些情況下,路徑可能會維持無法存取約 70 分鐘。
更改或移除資料夾
編輯專案中的資料夾宣告,並使用 npx rayfin up 或 npx rayfin up storage apply 套用。
Warning
從套用設定中移除資料夾會使該資料夾無法使用,並永久刪除其檔案。 在移除前,先備份你需要的檔案。 你無法還原資料夾。 在刪除完成前,你不能重複使用它的名字。
移除非空資料夾需要使用 --force 進行明確核准:
npx rayfin up storage apply --force
在使用 --force前先檢視變更。
此選項允許資料遺失;它不是例行的部署標誌。
移除後,資料夾無法使用,且其檔案會在背景被刪除。
如果清理沒完成,但你的結構仍有註冊資料夾,請重執行 npx rayfin up storage apply 並檢查輸出是否有警告。
如果已沒有任何資料夾處於已註冊狀態,請聯絡客服協助清理。
移除所有資料夾宣告並不會刪除已部署的資料夾。 不要把空的結構描述當作清理程序來使用。
監控儲存空間
在 Fabric 入口網站中,打開應用程式的管理檢視,選擇儲存以檢查檔案。 若可用,選擇 「指標」,再選擇 「儲存」 以查看儲存請求次數與請求錯誤率。
常見問題
我需要另外一個 lakehouse 或 Azure 儲存體 帳號嗎?
No. Fabric Apps 會使用與你的應用程式和工作空間相關聯的 OneLake 儲存空間。 你不需要另行建立 lakehouse 或 Azure 儲存體 帳戶。
在應用程式中啟用儲存空間會啟用 OneLake 租戶設定嗎?
No. 啟用資料與儲存功能是設定應用程式的服務;不會改變租戶政策。 你的 Fabric 管理員必須在先決條件中驗證 OneLake 設定。
應用程式使用者需要另外的 OneLake 憑證嗎?
No. 讓使用者登入你的應用程式,並使用儲存 SDK 與相同已驗證的用戶端工作階段。 用資料夾權限控制存取。 不支援匿名儲存存取。
如果無法上傳或下載檔案,我應該檢查什麼?
確認 OneLake 的 先決條件 設定是否允許你的應用程式進行儲存。 確保使用者已登入並擁有操作所需的資料夾權限。 請檢查 Rayfin 部署輸出中的儲存警告,並在重試前套用任何資料夾變更。