在 Fabric 应用中存储和管理文件

Fabric Apps Storage 基于 OneLake,允许你向应用添加文档、图片和附件。 用 Rayfin 定义文件夹和访问规则,然后用客户端 SDK 上传、列出、下载和删除文件。 在你的数据模型中保留结构化应用数据。

文件操作在开发期间和部署后都使用 Fabric 存储;没有本地存储仿真器。

Prerequisites

  • Fabric Apps project,以及 Node.js 20 或更高版本。
  • 为您的租户启用的 Fabric Apps。
  • 启用用户可以使用 Fabric 外部的应用访问存储在 OneLake 中的数据租户设置后,用户即可访问存储在 OneLake 中的数据。 参见 启用OneLake访问。
  • 具有已分配受支持 Fabric 容量的 Fabric 工作区的访问权限。 Power BI Pro 工作区不支持存储功能。
  • 部署应用并应用存储配置的权限。
  • 一个配置过 的数据服务,包括 services.data.dialect。
  • 为应用配置了Fabric认证,并为用户设置了登录流程。

启用OneLake访问

文件的上传和下载依赖于 OneLake 的访问权限。 请要求你的 Fabric 管理员启用 用户可使用 Fabric 外部应用访问存储在 OneLake 中的数据 租户设置。 它默认是整个组织都启用的。 Fabric 应用存储需要启用此设置。 这个设置通常控制的是来自 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.

检查生成的配置、文件夹权限和客户端的变更。 存储需要启用并配置数据服务。 每个文件夹都需要认证权限规则。 文件夹权限控制对文件的访问;路径仅组织内容。 有关权限的更多信息,请参见 定义数据权限。

应用配置

从项目根部署你的应用:

npx rayfin up

当启用存储时,完整部署会应用已注册的文件夹。 使用文件夹前请检查部署输出中的存储警告。 要重试失败的存储步骤或仅对现有部署应用文件夹更改,请执行:

npx rayfin up storage apply

成功全面部署后,你不需要运行仅存储命令。

针对远程存储进行开发

开始你的开发会话:

npx rayfin dev

通过使用默认的 Fabric 提供者,该命令会将已启用的存储声明应用到 Fabric 中的开发应用。 你的前端运行在本地,但文件操作读写远程文件。 使用开发应用,测试时避免使用生产数据。

要重新尝试当前开发部署的存储配置,请执行:

npx rayfin dev storage apply

在使用仅存储命令之前,请先启动一个完整 rayfin dev 会话。 重试命令使用当前部署,不接受 --workspace 或 --workspace-id。 Docker provider 不支持存储。

配置客户端

将存储连接到应用现有客户端,并保留其配置和登录流程。 设置提示可以帮助你为你的项目配置客户端。 登录和存储调用必须使用同一个客户端会话。 创建客户端并不会登录用户。

处理文件

以下示例使用你配置好的、已登录的 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 门户中,打开应用的管理视图,选择 存储 以检查其文件。 如有,选择 “指标”,然后选择 存储 以查看存储请求数量和请求错误率。

常见问题解答

我需要单独的湖仓或 Azure 存储 帐户吗?

No. Fabric Apps 使用与你的应用和工作区关联的 OneLake 存储。 你不需要单独创建湖屋或 Azure 存储 账户。

在应用中启用存储会激活 OneLake 租户设置吗?

No. 启用数据和存储功能是配置应用的服务;它不会改变租户政策。 你的 Fabric 管理员必须在先决条件中核实 OneLake 设置。

应用用户需要单独的OneLake凭证吗?

No. 让用户登录到你的应用,并使用同一认证客户端会话来使用存储 SDK。 通过文件夹权限控制访问。 不支持匿名存储访问。

如果我无法上传或下载文件,应该检查哪些问题?

确认 先决条件 中的 OneLake 设置是否允许你的应用使用存储。 确保用户已登录并具备操作所需的文件夹权限。 检查 Rayfin 部署输出中的存储警告,并在重试前应用任何文件夹更改。