Fabricアプリでのファイルの保存と管理

Fabric Apps StorageはOneLakeを基盤としており、ドキュメント、画像、添付ファイルを追加できます。 Rayfinでフォルダとアクセスルールを定義し、クライアントSDKを使ってファイルのアップロード、リスト、ダウンロード、削除を行います。 構造化アプリデータはデータモデル内に残しておく。

ファイル操作は開発中および展開後の両方でFabricストレージを使用します。ローカルストレージエミュレーターはありません。

Prerequisites

  • Fabric Apps プロジェクト と Node.js 20 以降。
  • ユーザーは外部アプリで OneLake に保存されたデータにアクセスできます Fabric テナント設定が有効になっています。 「 OneLakeアクセスを有効にする」をご覧ください。
  • サポートされたFabric容量が割り当てられたFabricワークスペースへのアクセス。 ストレージはPower BI Proのワークスペースではサポートされていません。
  • アプリのデプロイおよびストレージ設定の適用権限。
  • services.data.dialectを含む設定されたデータサービス。
  • アプリ用に設定されたFabric認証と、ユーザー向けのサインイン フロー。

OneLakeアクセスを有効にする

ファイルのアップロードとダウンロードは OneLake へのアクセスに依存します。 Fabric管理者に依頼し、「Users can access data stored in OneLake with apps external to Fabric」テナント設定を有効にしてもらってください。 組織全体でデフォルトで有効になっています。 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.

生成された設定、フォルダの権限、クライアントの変更を確認しましょう。 ストレージにはデータサービスの有効化と設定が必要です。 すべてのフォルダには認証済みユーザー向けの権限ルールが必要です。 フォルダ権限はファイルへのアクセスを制御し、パスは内容のみを整理します。 権限の詳細については、「 データ権限の定義」をご覧ください。

構成を適用する

プロジェクトのルートからアプリをデプロイします:

npx rayfin up

フルデプロイメントでは、ストレージが有効な場合、登録済みフォルダが適用されます。 フォルダを使う前に、デプロイの出力でストレージ警告を確認してください。 失敗したストレージステップをやり直すか、既存のデプロイにフォルダ変更のみを適用するには、以下を実行します:

npx rayfin up storage apply

フルデプロイが成功した後にストレージのみコマンドを実行する必要はありません。

リモート ストレージを使用して開発する

開発セッションの開始:

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を作成した場合は、アプリがそれを必要としなくなったら取り消してください。

ファイルを削除する

相対パスを指定してファイルを削除します:

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 Storageアカウントが必要ですか?

No. Fabric Appsは、アプリとワークスペースに関連付けられたOneLakeストレージを使用します。 別にレイクハウスやAzure Storageアカウントを作成する必要はありません。

アプリでストレージを有効にするとOneLakeのテナント設定は有効になりますか?

No. データとストレージを有効にするとアプリのサービスが設定されます。テナントポリシーは変わりません。 Fabric管理者は前提条件でOneLake設定を検証する必要があります。

アプリユーザーは別々のOneLake認証情報が必要ですか?

No. ユーザーをアプリにサインインさせ、同じ認証済みクライアントセッションでストレージSDKを使いましょう。 フォルダ権限でアクセスを制御します。 匿名ストレージアクセスはサポートされていません。

ファイルのアップロードやダウンロードができない場合、何を確認すればいいですか?

PrerequisitesのOneLake設定で、アプリでのストレージ利用が許可されていることを確認してください。 ユーザーがサインインしていて、操作に必要なフォルダ権限を持っていることを確認してください。 Rayfinのデプロイ出力でストレージ警告を確認し、フォルダの変更を適用してから再挑戦してください。