Udostępnij przez

Instrukcje: tworzenie skrótów w elemencie

W tym artykule wyjaśniono, jak zaimplementować funkcje skrótów w elemencie obciążenia usługi Microsoft Fabric w celu odwołowania się do danych z magazynów typu lakehouse lub zewnętrznych źródeł magazynu w chmurze, takich jak Amazon S3 bez kopiowania danych. Skróty umożliwiają aplikacji uzyskiwanie dostępu do danych z różnych źródeł i pracę z nimi za pośrednictwem ujednoliconego interfejsu obsługującego "obietnicę pojedynczej kopii" usługi OneLake.

Omówienie skrótów w usłudze Microsoft Fabric

Skróty w usłudze Microsoft Fabric umożliwiają dostęp do danych między domenami, chmurami i kontami, tworząc wirtualny widok danych znajdujących się w różnych lokalizacjach. Podczas tworzenia skrótu w elemencie obciążenia tworzysz odwołanie do danych bez fizycznego kopiowania go, co:

  • Zmniejsza koszty magazynowania i duplikowanie danych
  • Zapewnia spójność danych, zawsze wskazując dane źródłowe
  • Upraszcza dostęp do danych dla użytkowników za pośrednictwem ujednoliconej przestrzeni nazw
  • Zapewnia potencjalne korzyści wydajności dzięki inteligentnemu buforowaniu

Używanie kontrolki tworzenia skrótów

Zestaw narzędzi Fabric Extensibility Toolkit zawiera kontrolkę tworzenia skrótów, która upraszcza proces tworzenia skrótów. Ta kontrolka zapewnia standardowy interfejs użytkownika do tworzenia skrótów, podobnie jak w przypadku natywnych elementów sieci szkieletowej.

Aby użyć kontrolki tworzenia skrótów w swoim zadaniu:

  1. Zaimportuj kontrolkę z zestawu narzędzi Extensibility Toolkit.

    import { ShortcutCreationControl } from '@fabric/extensibility-toolkit';

  2. Dodaj kontrolkę do komponentu:

    <ShortcutCreationControl
  supportedSourceTypes=['Lakehouse', 'MyWorkloadName.MyItemName']}, // Specify which source types your workload supports
  supportedTargetTypes={['Lakehouse', 'MyWorkloadName.MyItemName']} // Specify which source types your workload supports
/>

Programowe tworzenie skrótów

Jeśli musisz programowo tworzyć skróty, możesz użyć OneLakeShortcutClient tego, który zapewnia uproszczony interfejs do zarządzania skrótami:

Konfigurowanie OneLakeShortcutClient

import { OneLakeShortcutClient } from '../clients/OneLakeShortcutClient';
import { WorkloadClientAPI } from "@ms-fabric/workload-client";

// Initialize the client in your component or service
const shortcutClient = new OneLakeShortcutClient(workloadClient);

Tworzenie różnych typów skrótów

Skróty oneLake (sieć szkieletowa do sieci szkieletowej):

// Create a shortcut to another Fabric item (Lakehouse, KQL Database, etc.)
const oneLakeShortcut = await shortcutClient.createOneLakeShortcut(
  workspaceId,           // Current workspace ID
  itemId,                // Current item ID
  'SharedLakehouse',     // Shortcut name
  '/Files',              // Target path in current item
  'source-workspace-id', // Source workspace ID
  'source-item-id',      // Source item ID (Lakehouse, etc.)
  '/Tables/Customers'    // Optional: specific path in source item
);

Skróty Amazon S3:

// Create an S3 shortcut
const s3Shortcut = await shortcutClient.createS3Shortcut(
  workspaceId,
  itemId,
  'S3CustomerData',      // Shortcut name
  '/Files',              // Target path in your item
  's3-connection-id',    // S3 connection ID (configured in Fabric)
  'my-bucket',           // S3 bucket name
  '/customer-data'       // Path within bucket
);

Skróty usługi Azure Data Lake Storage Gen2:

// Create an ADLS Gen2 shortcut
const adlsShortcut = await shortcutClient.createAdlsGen2Shortcut(
  workspaceId,
  itemId,
  'ADLSData',            // Shortcut name
  '/Files',              // Target path in your item
  'adls-connection-id',  // ADLS Gen2 connection ID
  'mycontainer',         // Container name
  '/raw-data/analytics'  // Path within container
);

Zarządzanie istniejącymi skrótami

// List all shortcuts in a folder
const shortcuts = await shortcutClient.getAllShortcuts(workspaceId, itemId, '/Files');

// Get a specific shortcut
const shortcut = await shortcutClient.getShortcut(workspaceId, itemId, '/Files/MyShortcut');

// Delete a shortcut
await shortcutClient.deleteShortcut(workspaceId, itemId, '/Files/MyShortcut');

// Filter shortcuts by type
const oneLakeShortcuts = await shortcutClient.getOneLakeShortcuts(workspaceId, itemId, '/Files');
const s3Shortcuts = await shortcutClient.getS3Shortcuts(workspaceId, itemId, '/Files');
const adlsShortcuts = await shortcutClient.getAdlsGen2Shortcuts(workspaceId, itemId, '/Files');

// Search shortcuts by name pattern
const customerShortcuts = await shortcutClient.searchShortcutsByName(
  workspaceId, itemId, '/Files', 'customer'
);

Typy skrótów i konfiguracja źródła

Obciążenie może obsługiwać różne typy skrótów w zależności od przypadku użycia. OneLakeShortcutClient udostępnia metody pomocnicze dla typowych skrótów:

Skróty oneLake (elementy sieci szkieletowej)

Skróty OneLake umożliwiają obciążeniu dostęp do danych przechowywanych w innych elementach Fabric, takich jak Lakehouses, bazy danych KQL, itp.

// Using the OneLakeShortcutClient helper method
const lakehouseShortcut = await shortcutClient.createOneLakeShortcut(
  workspaceId,
  itemId,
  "SharedLakehouse",     // Shortcut name
  "/Files",              // Target path in your item
  "source-workspace-id", // Source workspace ID
  "lakehouse-item-id",   // Source lakehouse ID
  "/Tables/myTable"      // Optional: specific path in source
);

Skróty Amazon S3

Skróty S3 umożliwiają dostęp do danych przechowywanych w zasobnikach Amazon S3:

// Using the OneLakeShortcutClient helper method
const s3Shortcut = await shortcutClient.createS3Shortcut(
  workspaceId,
  itemId,
  "CustomerDataS3",      // Shortcut name
  "/Files",              // Target path in your item
  "s3-connection-id",    // S3 connection ID (pre-configured in Fabric)
  "my-bucket",           // S3 bucket name
  "/customer-folder"     // Path within the bucket
);

Praca z danymi skrótów

Po utworzeniu skrótu, zadania robocze mogą pracować z danymi przy użyciu OneLakeStorageClient. Ten klient udostępnia metody interakcji zarówno z zwykłą zawartością OneLake, jak i danymi skrótów za pośrednictwem ujednoliconego interfejsu.

Konfigurowanie klienta OneLakeStorageClient

import { OneLakeStorageClient } from '../clients/OneLakeStorageClient';
import { WorkloadClientAPI } from "@ms-fabric/workload-client";

// Initialize the storage client
const storageClient = new OneLakeStorageClient(workloadClient);

Praca z metadanymi skrótów

Podczas pracy ze skrótami ważne jest, aby zrozumieć, że metadane skrótów i zawartość skrótów są pobierane inaczej:

Uzyskiwanie informacji o skrótach

Aby zdobyć informacje o skrótach w ścieżce, użyj getPathMetadata z shortcutMetadata: true:

// Get metadata for a path including shortcut information
const metadata = await storageClient.getPathMetadata(
  workspaceId,
  'itemId/Files',       // Path to check for shortcuts
  false,                // recursive: false for current level only
  true                  // shortcutMetadata: true to include shortcut info
);

// Filter for shortcuts
const shortcuts = metadata.paths.filter(path => path.isShortcut);

console.log('Found shortcuts:', shortcuts.map(s => ({
  name: s.name,
  isShortcut: s.isShortcut,
  lastModified: s.lastModified
})));

Uzyskiwanie dostępu do zawartości skrótów

Ważne

Gdy shortcutMetadata: true, otrzymujesz tylko informacje na temat samego skrótu, a nie zawartości wewnątrz skrótu. Aby uzyskać dostęp do rzeczywistych danych w ramach skrótu, musisz wykonać oddzielne wywołanie przy użyciu ścieżki skrótu:

// First, get the shortcuts in the directory
const dirMetadata = await storageClient.getPathMetadata(
  workspaceId,
  'itemId/Files',
  false,
  true // Get shortcut metadata
);

// Find a specific shortcut
const myShortcut = dirMetadata.paths.find(path => 
  path.isShortcut && path.name === 'MyS3Shortcut'
);

if (myShortcut) {
  // Now get the content INSIDE the shortcut
  const shortcutContent = await storageClient.getPathMetadata(
    workspaceId,
    myShortcut.path,                    // Use the shortcut path
    true,                               // recursive: true to see all content
    false                              // shortcutMetadata: false to get actual content
  );

  console.log('Content inside shortcut:', shortcutContent.paths);
}

Odczytywanie i zapisywanie danych dotyczących skrótów klawiszowych

Po utworzeniu struktury zawartości skrótów możesz odczytywać i zapisywać pliki tak jak zwykłe pliki OneLake:

// Read a file from within a shortcut
const fileContent = await storageClient.readFileAsText(
  OneLakeStorageClient.getPath(workspaceId, itemId, 'Files/MyS3Shortcut/data.csv')
);

// Write a file to a shortcut (if the shortcut supports writes)
await storageClient.writeFileAsText(
  OneLakeStorageClient.getPath(workspaceId, itemId, 'Files/MyS3Shortcut/output.txt'),
  'Processed data content'
);

Używanie opakowania elementu dla uproszczenia dostępu

W przypadku kodu czystszego można użyć elementu OneLakeStorageClientItemWrapper:

// Create an item wrapper for simplified access
const itemStorage = storageClient.createItemWrapper({
  workspaceId: workspaceId,
  id: itemId
});

// Get shortcuts in the Files directory
const filesMetadata = await itemStorage.getPathMetadata(
  'Files',
  false,
  true // Include shortcut metadata
);

// Access content within a shortcut
const shortcutContent = await itemStorage.getPathMetadata(
  'Files/MyShortcut',
  true,  // recursive
  false  // Get actual content, not shortcut metadata
);

// Read/write files with simpler paths
const fileContent = await itemStorage.readFileAsText('Files/MyShortcut/data.txt');
await itemStorage.writeFileAsText('Files/MyShortcut/processed.txt', 'Result data');

Kompletny przykład: Praca z danymi skrótów

async function analyzeShortcutData(workspaceId: string, itemId: string) {
  const storageClient = new OneLakeStorageClient(workloadClient);
  
  try {
    // Step 1: Find all shortcuts in the Files directory
    const dirMetadata = await storageClient.getPathMetadata(
      workspaceId,
      `${itemId}/Files`,
      false,
      true // Get shortcut info
    );

    const shortcuts = dirMetadata.paths.filter(path => path.isShortcut);
    console.log(`Found ${shortcuts.length} shortcuts`);

    // Step 2: For each shortcut, analyze its content
    for (const shortcut of shortcuts) {
      console.log(`\nAnalyzing shortcut: ${shortcut.name}`);
      
      // Get the content inside this shortcut
      const shortcutContent = await storageClient.getPathMetadata(
        workspaceId,
        `${itemId}/Files/${shortcut.name}`,
        true,  // recursive to see all files
        false  // get actual content, not shortcut metadata
      );

      console.log(`  - Contains ${shortcutContent.paths.length} items`);
      
      // List all files in the shortcut
      const files = shortcutContent.paths.filter(p => !p.isDirectory);
      for (const file of files) {
        console.log(`  - File: ${file.name} (${file.contentLength} bytes)`);
        
        // Optionally read the file content
        if (file.name.endsWith('.txt') || file.name.endsWith('.csv')) {
          try {
            const content = await storageClient.readFileAsText(
              OneLakeStorageClient.getPath(workspaceId, itemId, `Files/${shortcut.name}/${file.name}`)
            );
            console.log(`    Preview: ${content.substring(0, 100)}...`);
          } catch (error) {
            console.log(`    Could not read file: ${error.message}`);
          }
        }
      }
    }
  } catch (error) {
    console.error('Error analyzing shortcut data:', error);
  }
}

Zagadnienia dotyczące zabezpieczeń

Skróty szanują kontekst zabezpieczeń użytkownika:

  • W przypadku wewnętrznych źródeł Fabric (takich jak Lakehouses) używana jest tożsamość wywołującego użytkownika.
  • W przypadku źródeł zewnętrznych (takich jak S3) używane są poświadczenia połączenia określone podczas tworzenia skrótów

Upewnij się, że obciążenie prawidłowo obsługuje uwierzytelnianie i udostępnia odpowiednie elementy interfejsu użytkownika w celu bezpiecznego wprowadzania szczegółów połączenia.

Treści powiązane

  • Last updated on