Procedura: Archiviare i dati in OneLake

Ogni elemento fabric ha accesso all'archiviazione OneLake, che offre un modo sicuro e scalabile per archiviare i file associati all'elemento. Questa guida illustra come caricare i file nel tuo elemento Fabric usando il FabricPlatformAPIClient e l'OneLakeClient sottostante.

Informazioni sull'archiviazione degli elementi in Fabric

Ogni elemento in Fabric ha una propria area di archiviazione dedicata in OneLake. Questa risorsa di archiviazione è organizzata in cartelle, con le cartelle principali:

• File - Per l'archiviazione di file e documenti generali
• Tabelle - Per l'archiviazione dei dati della tabella

Prerequisiti

Prima di caricare i file nell'elemento, è necessario:

• Un'area di lavoro di Fabric valida
• Elemento esistente in cui si vuole caricare il file
• Autorizzazioni appropriate per la scrittura nell'elemento

Creazione di FabricPlatformAPIClient

Per prima cosa, creare un'istanza FabricPlatformAPIClient.

import { getWorkloadClient } from "../controller/WorkloadClient";
import { FabricPlatformAPIClient } from "../clients/FabricPlatformAPIClient";

// Create client using the current user's context
const fabricClient = FabricPlatformAPIClient.create(getWorkloadClient());

Esempio: Caricamento di un file di testo in un elemento

Ecco come caricare un file di testo in un elemento usando il client OneLake:

async function uploadTextFileToItem(
  workspaceId: string, 
  itemId: string, 
  fileName: string, 
  content: string
) {
  try {
    // Get the FabricPlatformAPIClient
    const fabricClient = FabricPlatformAPIClient.create(getWorkloadClient());
    
    // Access the OneLake client
    const oneLakeClient = fabricClient.oneLake;
    
    // Generate the file path in OneLake for this item
    // This follows the pattern: workspaceId/itemId/Files/fileName
    const filePath = oneLakeClient.constructor.getFilePath(workspaceId, itemId, fileName);
    
    // Write the text content to the file
    await oneLakeClient.writeFileAsText(filePath, content);
    
    console.log(`Successfully uploaded ${fileName} to item ${itemId}`);
    return true;
  } catch (error) {
    console.error("Error uploading file to item:", error);
    throw error;
  }
}

Esempio: Caricamento di un file binario in un elemento

Per i file binari come immagini o PDF, è necessario convertire prima il file in base64:

async function uploadBinaryFileToItem(
  workspaceId: string,
  itemId: string,
  fileName: string,
  fileData: ArrayBuffer // Binary file data
) {
  try {
    const fabricClient = FabricPlatformAPIClient.create(getWorkloadClient());
    const oneLakeClient = fabricClient.oneLake;
    
    // Convert binary data to base64
    const base64Content = arrayBufferToBase64(fileData);
    
    // Generate the file path
    const filePath = oneLakeClient.constructor.getFilePath(workspaceId, itemId, fileName);
    
    // Write the binary content to the file
    await oneLakeClient.writeFileAsBase64(filePath, base64Content);
    
    console.log(`Successfully uploaded binary file ${fileName} to item ${itemId}`);
    return true;
  } catch (error) {
    console.error("Error uploading binary file to item:", error);
    throw error;
  }
}

// Helper function to convert ArrayBuffer to base64
function arrayBufferToBase64(buffer: ArrayBuffer): string {
  let binary = '';
  const bytes = new Uint8Array(buffer);
  const len = bytes.byteLength;
  
  for (let i = 0; i < len; i++) {
    binary += String.fromCharCode(bytes[i]);
  }
  
  return btoa(binary);
}

Esempio: Caricamento di un file dal browser

Se si sta creando un'interfaccia Web, è possibile usare questa funzione per gestire i caricamenti di file da un input di file:

async function handleFileUpload(
  workspaceId: string,
  itemId: string,
  fileInputElement: HTMLInputElement
) {
  if (!fileInputElement.files || fileInputElement.files.length === 0) {
    console.warn("No file selected");
    return false;
  }
  
  const file = fileInputElement.files[0];
  const fileName = file.name;
  
  try {
    // Read the file as ArrayBuffer
    const fileBuffer = await readFileAsArrayBuffer(file);
    
    // Upload based on file type
    if (file.type.startsWith('text/')) {
      // For text files, convert to string and upload as text
      const textDecoder = new TextDecoder();
      const textContent = textDecoder.decode(fileBuffer);
      
      return await uploadTextFileToItem(workspaceId, itemId, fileName, textContent);
    } else {
      // For binary files, upload as base64
      return await uploadBinaryFileToItem(workspaceId, itemId, fileName, fileBuffer);
    }
  } catch (error) {
    console.error("Error processing file upload:", error);
    throw error;
  }
}

// Helper function to read file as ArrayBuffer
function readFileAsArrayBuffer(file: File): Promise<ArrayBuffer> {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result as ArrayBuffer);
    reader.onerror = reject;
    reader.readAsArrayBuffer(file);
  });
}

Gestione dei file nel tuo elemento

Dopo aver caricato i file, è anche possibile:

Controllare se esiste un file

async function checkFileExists(workspaceId: string, itemId: string, fileName: string) {
  const fabricClient = FabricPlatformAPIClient.create(getWorkloadClient());
  const filePath = fabricClient.oneLake.constructor.getFilePath(workspaceId, itemId, fileName);
  
  return await fabricClient.oneLake.checkIfFileExists(filePath);
}

Leggere il contenuto del file

async function readTextFile(workspaceId: string, itemId: string, fileName: string) {
  const fabricClient = FabricPlatformAPIClient.create(getWorkloadClient());
  const filePath = fabricClient.oneLake.constructor.getFilePath(workspaceId, itemId, fileName);
  
  return await fabricClient.oneLake.readFileAsText(filePath);
}

Eliminare un file

async function deleteFile(workspaceId: string, itemId: string, fileName: string) {
  const fabricClient = FabricPlatformAPIClient.create(getWorkloadClient());
  const filePath = fabricClient.oneLake.constructor.getFilePath(workspaceId, itemId, fileName);
  
  await fabricClient.oneLake.deleteFile(filePath);
  console.log(`File ${fileName} deleted successfully`);
}

Procedure consigliate per i caricamenti di file

• Usare formati di file appropriati: considerare lo scopo del file e usare i formati ampiamente supportati.
• Gestire gli errori normalmente: includere sempre la gestione degli errori per problemi di rete o problemi di autorizzazione.
• Convalidare le dimensioni dei file: i file di grandi dimensioni potrebbero richiedere più tempo per il caricamento e l'elaborazione.
• Controllare le autorizzazioni: assicurarsi che l'utente disponga delle autorizzazioni appropriate prima di tentare il caricamento.
• Usare prefissi o cartelle di file: per elementi complessi con molti file, è consigliabile organizzarli in sottocartelle.

Uso di OneLakeClientItemWrapper

Per semplificare l'accesso ai file di elementi, è possibile usare :OneLakeClientItemWrapper

async function uploadFileWithItemWrapper(item, fileName, content) {
  const fabricClient = FabricPlatformAPIClient.create(getWorkloadClient());
  
  // Create a wrapper for simpler access to this specific item
  const itemWrapper = fabricClient.oneLake.createItemWrapper({
    workspaceId: item.workspaceId,
    itemId: item.id
  });
  
  // Upload directly to the item (no need to specify paths)
  await itemWrapper.writeFileAsText(fileName, content);
  
  // Read the file back
  const fileContent = await itemWrapper.readFileAsText(fileName);
  
  console.log(`File uploaded and read back: ${fileContent.substring(0, 50)}...`);
}

Questo wrapper semplifica le operazioni sui file gestendo automaticamente la costruzione del percorso completo.