Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Fabric Apps Storage è costruito su OneLake e ti permette di aggiungere documenti, immagini e allegati alla tua app. Definisci cartelle e regole di accesso con Rayfin, poi usa il client SDK per caricare, elencare, scaricare ed eliminare file. Conserva dati strutturati dell'app nei tuoi modelli dati.
Le operazioni file utilizzano lo storage Fabric durante lo sviluppo e anche dopo il deployment; non esiste un emulatore di storage locale.
Prerequisites
- Un progetto Fabric Apps e Node.js 20 o versione successiva.
- Gli utenti possono accedere ai dati memorizzati in OneLake con le app esterne a Fabric con l'impostazione del tenant Gli utenti possono accedere ai dati memorizzati in OneLake con le app esterne a Fabric abilitata. Vedi Abilitare l'accesso a OneLake.
- Accesso a uno spazio di lavoro Fabric con una capacità Fabric supportata assegnata. L'archiviazione non è supportata negli spazi di lavoro di Power BI Pro.
- Permesso di distribuire l'app e applicare la sua configurazione di archiviazione.
- Un servizio dati configurato, inclusi
services.data.dialect. - Autenticazione Fabric configurata per l'app e un flusso di accesso per gli utenti.
Abilita l'accesso a OneLake
Il caricamento e il download dei file dipendono dall'accesso a OneLake. Chiedi al tuo amministratore Fabric di abilitare l'impostazione del tenant Gli utenti possono accedere ai dati archiviati in OneLake con app esterne a Fabric. È abilitato per tutta l'organizzazione di default. Fabric Apps Storage richiede che questa impostazione sia abilitata. Questa impostazione regola generalmente l'accesso da applicazioni esterne a Fabric, non solo dalla tua app. Devi anche definire i permessi delle cartelle per controllare a quali file ogni utente dell'app può accedere. Per maggiori informazioni, consulta impostazioni del tenant OneLake.
Abilita l'archiviazione
Usa GitHub Copilot o un altro agente di programmazione con accesso al tuo progetto e terminale per configurare lo storage. Ad esempio, usa il seguente prompt:
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.
Rivedi la configurazione generata, i permessi delle cartelle e le modifiche al client. Lo storage richiede che il servizio Data sia abilitato e configurato. Ogni cartella richiede una regola di autorizzazione per utenti autenticati. I permessi delle cartelle controllano l'accesso ai file; i percorsi organizzano solo il contenuto. Per maggiori informazioni sui permessi, vedi Definisci permessi dati.
Applicare la configurazione
Distribuisci la tua app dalla radice del progetto:
npx rayfin up
Una distribuzione completa applica le cartelle registrate quando lo Storage è abilitato. Controlla l'output di distribuzione per avvisi di archiviazione prima di usare le cartelle. Per riprovare un passaggio di storage non riuscito o applicare solo modifiche alle cartelle a un deployment esistente, esegui:
npx rayfin up storage apply
Non è necessario eseguire il comando storage-only dopo un deployment completo riuscito.
Sviluppare usando lo storage remoto
Inizia la tua sessione di sviluppo:
npx rayfin dev
Utilizzando il provider Fabric predefinito, questo comando applica le dichiarazioni di archiviazione abilitate alla tua app di sviluppo in Fabric. Il tuo frontend gira localmente, ma le operazioni di file leggono e scrivono file remoti. Usa un'app di sviluppo ed evita i dati di produzione durante i test.
Per riprovare la configurazione di archiviazione per il deployment di sviluppo attivo, esegui:
npx rayfin dev storage apply
Avvia una sessione completa rayfin dev prima di usare questo comando relativo solo all'archiviazione.
Il comando retry usa il deployment attivo e non accetta --workspace o --workspace-id.
Lo storage non è supportato dal provider Docker.
Configurare il client
Collega lo storage al client esistente della tua app e mantieni la configurazione e il flusso di accesso. Il prompt di configurazione può aiutarti a configurare il client per il tuo progetto. Le chiamate di accesso e di archiviazione devono utilizzare la stessa sessione client. La creazione del client non comporta l'accesso di un utente.
Lavorare con i file
I seguenti esempi utilizzano la tua istanza configurata e logata client e la cartella documents .
I percorsi degli oggetti sono relativi a quella cartella.
Da utilizzare / tra i segmenti del percorso e includere il nome del file per le operazioni di upload, download e cancellazione.
Non usare un / iniziale o finale, barre rovesciate, segmenti vuoti, segmenti . o segmenti ...
Carica un file
Specifica un browser File selezionato dall'utente:
async function uploadDocument(file: File) {
return client.storage.documents.upload('reports/quarterly-report.pdf', file, {
contentType: 'application/pdf',
contentDisposition: 'attachment; filename="quarterly-report.pdf"',
});
}
Dopo che il caricamento è terminato, usa lo stesso percorso per scaricare o eliminare il file.
Caricare di nuovo nello stesso percorso segue l'impostazione della cartella onConflict.
Il valore opzionale contentDisposition memorizza metadati che descrivono come il file dovrebbe essere presentato, come un allegato con un nome di file suggerito.
Elencare file
Elenca dalla radice della cartella, oppure fornisci un percorso di directory per restringere i risultati:
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);
}
Chiama list() senza un percorso di directory per elencare dalla radice della cartella.
Usa il token di continuazione restituito per recuperare ulteriori pagine.
L'API di archiviazione può includere file in stato Deleting nei risultati delle liste.
Non puoi caricare o scaricare un file in quello stato.
Se la cancellazione non si completa, riprova a cancellare il file.
Scaricare un file
Usa lo stesso percorso relativo che hai fornito durante il caricamento:
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();
Usa il risultato Blob nel flusso di visualizzazione o download della tua app per i file delimitati.
Questa conversione memorizza l'intero file in memoria.
Per file grandi, consuma result.stream invece in modo incrementale.
Se crei un URL oggetto con URL.createObjectURL, revocalo quando l'app non ne ha più bisogno.
Eliminare un file
Elimina il file tramite il relativo percorso:
await client.storage.documents.delete('reports/quarterly-report.pdf');
Se un'operazione di upload o cancellazione viene interrotta, potrebbe temporaneamente bloccare un'altra operazione sullo stesso percorso. Attendere e riprovare. In alcuni casi, il percorso può rimanere bloccato per circa 70 minuti.
Modifica o rimuovi cartelle
Modifica le dichiarazioni delle cartelle nel tuo progetto e applicale con npx rayfin up o npx rayfin up storage apply.
Warning
La rimozione di una cartella da una configurazione applicata la rende indisponibile e cancella permanentemente i suoi file. Fai un backup di tutti i file di cui hai bisogno prima di applicare la rimozione. Non puoi ripristinare la cartella. Non puoi riutilizzare il suo nome finché la cancellazione non è terminata.
La rimozione di una cartella non vuota richiede un'approvazione esplicita con --force:
npx rayfin up storage apply --force
Rivedi la modifica prima di usare --force.
Questa opzione permette la perdita di dati; non è un flag di distribuzione di routine.
Dopo la rimozione, la cartella non è disponibile mentre i suoi file vengono cancellati in background.
Se la pulizia non si completa e il tuo schema ha ancora cartelle registrate, riesegui npx rayfin up storage apply e controlla l'output per eventuali avvisi.
Se non rimangono cartelle registrate, contatta l'assistenza per assistenza nella pulizia.
La rimozione di tutte le dichiarazioni di cartelle non cancella le cartelle distribuite. Non usare uno schema vuoto come procedura di pulizia.
Monitorare l'archiviazione
Nel portale Fabric, apri la visuale di gestione della tua app e seleziona Storage per ispezionare i suoi file. Quando disponibili, seleziona Metriche, poi seleziona Storage per vedere il conteggio delle richieste di archiviazione e il tasso di errore delle richieste.
Domande frequenti
Ho bisogno di un account separato su lakehouse o Archiviazione di Azure?
No. Fabric Apps utilizza lo storage OneLake associato alla tua app e al tuo spazio di lavoro. Non è necessario creare un lakehouse separato o un account Archiviazione di Azure separato.
L'abilitazione dello storage nell'app abilita l'impostazione del tenant OneLake?
No. Abilitare Data and Storage configura i servizi della tua app; non cambia i criteri del tenant. Il tuo amministratore di Fabric deve verificare l'impostazione OneLake nei prerequisiti.
Gli utenti dell'app hanno bisogno di credenziali OneLake separate?
No. Fai accedere gli utenti alla tua app e usa l'SDK di archiviazione con la stessa sessione client autenticata. Controlla l'accesso con i permessi delle cartelle. L'accesso anonimo allo storage non è supportato.
Cosa dovrei controllare se non posso caricare o scaricare file?
Confermare che l'impostazione OneLake nei prerequisiti consenta lo spazio di archiviazione per la tua app. Assicurati che l'utente sia connesso e abbia i permessi di cartella necessari per l'operazione. Controlla l'output di distribuzione di Rayfin per avvisi sullo storage e applica eventuali modifiche alle cartelle prima di riprovare.