Speichern und verwalten Sie Dateien in Fabric Apps

Fabric Apps Storage basiert auf OneLake und ermöglicht es Ihnen, Dokumente, Bilder und Anhänge zu Ihrer App hinzuzufügen. Definieren Sie Ordner und Zugriffsregeln mit Rayfin, und verwenden Sie dann das Client-SDK, um Dateien hochzuladen, aufzulisten, herunterzuladen und zu löschen. Speichern Sie strukturierte App-Daten in Ihren Datenmodellen.

Dateioperationen verwenden Fabric-Speicher sowohl während der Entwicklung als auch nach der Bereitstellung; es gibt keinen lokalen Speicher-Emulator.

Prerequisites

  • Ein Fabric Apps-Projekt und Node.js 20 oder später.
  • Fabric Apps für Ihren Mandanten aktiviert.
  • Die Tenant-Einstellung „Benutzer können mit Apps außerhalb von Fabric auf in OneLake gespeicherte Daten zugreifen“ ist aktiviert. Siehe OneLake-Zugang aktivieren.
  • Zugang zu einem Fabric-Arbeitsbereich mit einer zugewiesenen unterstützten Fabric-Kapazität. Speicher wird in Power BI Pro-Arbeitsbereichen nicht unterstützt.
  • Berechtigung, die App auszurollen und ihre Speicherkonfiguration anzuwenden.
  • Ein konfigurierter Data Service, einschließlich services.data.dialect.
  • Für die App ist Fabric-Authentifizierung konfiguriert und für ihre Nutzer ein Anmeldeablauf eingerichtet.

OneLake-Zugang aktivieren

Datei-Uploads und -downloads hängen vom OneLake-Zugang ab. Bitten Sie Ihren Fabric-Administrator, die Mandanteneinstellung Users can access data stored in OneLake with apps external to Fabric zu aktivieren. Es ist standardmäßig für die gesamte Organisation aktiviert. Fabric Apps Storage erfordert, dass diese Einstellung aktiviert ist. Diese Einstellung regelt den Zugriff von Anwendungen außerhalb von Fabric allgemein, nicht nur deine App. Du musst außerdem Ordnerberechtigungen definieren, um zu steuern, auf welche Dateien jeder App-Nutzer zugreifen kann. Weitere Informationen finden Sie unter OneLake-Mandanteneinstellungen.

Speicher aktivieren

Nutze GitHub Copilot oder einen anderen Coding-Agenten mit Zugriff auf dein Projekt und Terminal, um Speicher zu konfigurieren. Verwenden Sie zum Beispiel folgende Eingabeaufforderung:

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.

Überprüfen Sie die generierte Konfiguration, Ordnerberechtigungen und Client-Änderungen. Der Speicher erfordert, dass der Datendienst aktiviert und konfiguriert wird. Jeder Ordner benötigt eine authentifizierte Berechtigungsregel. Ordnerberechtigungen steuern den Zugriff auf Dateien; Pfade organisieren nur den Inhalt. Weitere Informationen zu Berechtigungen finden Sie unter Datenberechtigungen definieren.

Anwenden der Konfiguration

Stelle deine App aus dem Projektstammverzeichnis bereit:

npx rayfin up

Eine vollständige Bereitstellung wendet die registrierten Ordner an, wenn Storage aktiviert ist. Überprüfen Sie die Bereitstellungsausgabe auf Speicherwarnungen, bevor Sie die Ordner verwenden. Um einen fehlgeschlagenen Speicherschritt erneut zu versuchen oder nur Ordneränderungen auf eine bestehende Bereitstellung anzuwenden, führen Sie aus:

npx rayfin up storage apply

Du musst den Storage-only-Befehl nach einer erfolgreichen vollständigen Bereitstellung nicht ausführen.

Mit Remote-Speicher entwickeln

Beginnen Sie Ihre Entwicklungssitzung:

npx rayfin dev

Durch die Verwendung des Standard-Fabric-Providers wendet dieser Befehl aktivierte Speicherdeklarationen auf Ihre Entwicklungs-App in Fabric an. Dein Frontend läuft lokal, aber Dateioperationen lesen aus und schreiben in entfernte Dateien. Nutze eine Entwicklungs-App und vermeide Produktionsdaten während des Tests.

Um die Speicherkonfiguration für die aktive Entwicklungsbereitstellung erneut auszuführen, führen Sie aus:

npx rayfin dev storage apply

Starte eine komplette rayfin dev Sitzung, bevor du diesen Storage-only-Befehl verwendest. Der Retry-Befehl verwendet die aktive Bereitstellung und akzeptiert weder --workspace noch --workspace-id. Speicher wird vom Docker-Anbieter nicht unterstützt.

Konfigurieren des Clients

Verbinden Sie den Speicher mit dem bestehenden Client Ihrer App und behalten Sie dessen Konfigurations- und Anmeldeablauf bei. Der Setup-Prompt kann dir helfen, den Client für dein Projekt zu konfigurieren. Anmelde- und Speicheraufrufe müssen dieselbe Client-Sitzung verwenden. Durch das Erstellen eines Clients wird kein Benutzer angemeldet.

Arbeiten mit Dateien

Die folgenden Beispiele verwenden Ihre konfigurierte, angemeldete client Instanz und den Ordner documents . Objektpfade sind relativ zu diesem Ordner. Verwenden / Sie zwischen Pfadsegmenten und fügen Sie den Dateinamen für Upload-, Download- und Löschoperationen hinzu. Verwenden Sie kein führendes oder nachgestelltes /, keine Backslashes, leere Segmente, . Segmente oder .. Segmente.

Hochladen einer Datei

Übergeben Sie einen vom Nutzer ausgewählten Browser 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"',
  });
}

Nachdem der Upload abgeschlossen ist, nutze denselben Pfad, um die Datei herunterzuladen oder zu löschen. Das Uploaden auf denselben Pfad folgt der onConflict Einstellung des Ordners. Der optionale contentDisposition Wert speichert Metadaten, die beschreiben, wie die Datei präsentiert werden soll, zum Beispiel einen Anhang mit einem vorgeschlagenen Dateinamen.

Dateien auflisten

Liste vom Stammordner auf oder gib einen Verzeichnispfad an, um die Ergebnisse einzugrenzen:

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);
}

Rufen Sie list() ohne Verzeichnispfad auf, um ab dem Stammordner aufzulisten. Verwenden Sie das zurückgegebene Fortsetzungstoken, um zusätzliche Seiten abzurufen. Die Speicher-API kann Dateien in einem Deleting Zustand in den Ergebnissen des Listenaufrufs enthalten. Du kannst in diesem Zustand keine Datei hoch- oder herunterladen. Wenn die Löschung nicht abgeschlossen ist, versuche erneut, die Datei zu löschen.

Herunterladen einer Datei

Verwenden Sie denselben relativen Pfad, den Sie beim Hochladen angegeben haben:

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();

Verwenden Sie den resultierenden Blob im Anzeige- oder Download-Fluss Ihrer App für begrenzte Dateien. Diese Konvertierung puffert die gesamte Datei im Speicher. Verarbeiten Sie result.stream für große Dateien stattdessen schrittweise. Wenn du eine Objekt-URL mit URL.createObjectURLerstellst, widerrufe sie, wenn die App sie nicht mehr benötigt.

Löschen einer Datei

Löschen Sie die Datei über ihren relativen Pfad:

await client.storage.documents.delete('reports/quarterly-report.pdf');

Wenn eine Upload- oder Löschoperation unterbrochen wird, kann dies vorübergehend eine andere Operation auf demselben Pfad blockieren. Warten Sie, und wiederholen Sie den Vorgang. In manchen Fällen kann der Pfad etwa 70 Minuten lang blockiert bleiben.

Ordner ändern oder entfernen

Bearbeite Ordnerdeklarationen in deinem Projekt und wende sie über npx rayfin up oder npx rayfin up storage apply an.

Warning

Das Entfernen eines Ordners aus einer angewandten Konfiguration macht ihn nicht verfügbar und löscht seine Dateien dauerhaft. Sichere alle benötigten Dateien, bevor du das Entfernen durchführst. Du kannst den Ordner nicht wiederherstellen. Du kannst den Namen des Ordners erst wiederverwenden, wenn die Löschung abgeschlossen ist.

Das Entfernen eines nicht leeren Ordners erfordert eine ausdrückliche Genehmigung mit --force:

npx rayfin up storage apply --force

Überprüfen Sie die Veränderung, bevor Sie --force verwenden. Diese Option erlaubt Datenverlust; es handelt sich nicht um ein routinemäßiges Deployment-Flag.

Nach der Entfernung ist der Ordner nicht mehr verfügbar, während seine Dateien im Hintergrund gelöscht werden. Wenn die Bereinigung nicht abgeschlossen ist und Ihr Schema noch registrierte Ordner hat, führen Sie npx rayfin up storage apply erneut aus und überprüfen Sie die Ausgabe auf Warnungen. Wenn keine Ordner mehr registriert sind, wenden Sie sich an den Support, um Hilfe bei der Bereinigung zu erhalten.

Das Entfernen aller Ordnerdeklarationen löscht nicht die bereitgestellten Ordner. Verwenden Sie kein leeres Schema als Bereinigungsverfahren.

Überwachen des Speichers

Im Fabric-Portal öffnen Sie die Verwaltungsansicht Ihrer App und wählen Sie Speicher, um ihre Dateien zu inspizieren. Wenn verfügbar, wählen Sie Metriken und dann Speicher, um die Anzahl der Speicheranfragen und die Fehlerquote der Anfragen zu sehen.

Häufig gestellte Fragen

Brauche ich ein separates Lakehouse- oder Azure Storage-Konto?

No. Fabric Apps nutzt OneLake-Speicher, der mit Ihrer App und Ihrem Arbeitsbereich verknüpft ist. Du musst kein separates Lakehouse- oder Azure Storage-Konto erstellen.

Wird durch das Aktivieren des Speichers in der App die OneLake-Mandanteneinstellung aktiviert?

No. Das Aktivieren von Daten und Speicher konfiguriert die Dienste deiner App; es ändert die Mandantenrichtlinien nicht. Ihr Fabric-Administrator muss die OneLake-Einstellung in den Voraussetzungen überprüfen.

Benötigen App-Nutzer separate OneLake-Zugangsdaten?

No. Melden Sie Benutzer in Ihrer App an und verwenden Sie das Storage SDK mit derselben authentifizierten Client-Sitzung. Zugriff über Ordnerberechtigungen steuern. Anonymer Speicherzugriff wird nicht unterstützt.

Was sollte ich überprüfen, wenn ich keine Dateien hochladen oder herunterladen kann?

Bestätigen Sie, dass die OneLake-Einstellung in den Voraussetzungen die Speicherung für Ihre App erlaubt. Stellen Sie sicher, dass der Benutzer angemeldet ist und die für die Operation erforderlichen Ordnerberechtigungen hat. Überprüfen Sie die Rayfin-Bereitstellungsausgabe auf Speicherwarnungen und wenden Sie alle Ordneränderungen vor, bevor Sie es erneut versuchen.

Verwandte Inhalte

  • Zuletzt aktualisiert um