Instrukcje: przechowywanie danych w usłudze OneLake

Każdy element Fabric ma dostęp do magazynu OneLake, który zapewnia bezpieczny, skalowalny sposób przechowywania plików skojarzonych z elementem. W tym przewodniku wyjaśniono, jak ładować pliki do elementu Fabric przy użyciu FabricPlatformAPIClient i bazowego OneLakeClient elementu.

Zrozumienie magazynowania elementów w Fabric

Każdy element w usłudze Fabric ma własny dedykowany obszar przechowywania w usłudze OneLake. Pamięć jest podzielona na foldery, a główne foldery to:

• Pliki — do przechowywania ogólnych plików i dokumentów
• Tabele — do przechowywania danych tabeli

Wymagania wstępne

Przed przesłaniem plików do elementu musisz:

• Prawidłowy obszar roboczy Fabric
• Istniejący element, w którym chcesz przesłać plik
• Odpowiednie uprawnienia do zapisu w pliku

Tworzenie klienta FabricPlatformAPIClient

Najpierw utwórz instancję FabricPlatformAPIClient.

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

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

Przykład: przekazywanie pliku tekstowego do elementu

Poniżej przedstawiono sposób przekazywania pliku tekstowego do elementu przy użyciu klienta 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;
  }
}

Przykład: przesyłanie pliku binarnego do elementu

W przypadku plików binarnych, takich jak obrazy lub pliki PDF, należy najpierw przekonwertować plik na 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);
}

Przykład: przekazywanie pliku z przeglądarki

Jeśli tworzysz interfejs internetowy, możesz użyć tej funkcji do obsługi przesyłania plików z elementu wejściowego typu plik.

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

Zarządzanie plikami w twoim elemencie

Po przekazaniu plików można również:

Sprawdzanie, czy plik istnieje

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

Odczytywanie zawartości pliku

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

Usuwanie pliku

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

Najlepsze rozwiązania dotyczące przekazywania plików

• Użyj odpowiednich formatów plików: rozważ przeznaczenie pliku i użyj formatów, które są powszechnie obsługiwane.
• Spokojna obsługa błędów: zawsze uwzględniaj obsługę błędów w przypadku problemów z siecią lub problemów z uprawnieniami.
• Weryfikowanie rozmiarów plików: przekazywanie i przetwarzanie dużych plików może potrwać dłużej.
• Sprawdź uprawnienia: Upewnij się, że użytkownik ma odpowiednie uprawnienia przed przystąpieniem do przesyłania.
• Użyj prefiksów plików lub folderów: w przypadku złożonych elementów z wieloma plikami rozważ zorganizowanie ich w podfolderach.

Korzystanie z elementu OneLakeClientItemWrapper

Aby uprościć dostęp do plików elementów, można użyć polecenia 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)}...`);
}

Ta osłona upraszcza operacje na plikach, automatycznie obsługując pełną konstrukcję ścieżki.