Anleitung: Erstellen von Verknüpfungen in Ihrem Objekt

In diesem Artikel wird erläutert, wie Sie Verknüpfungsfunktionen in Ihrem Microsoft Fabric-Workloadelement implementieren, um auf Daten aus Lakehouses oder externen Cloudspeicherquellen wie Amazon S3 zu verweisen, ohne die Daten zu kopieren. Tastenkombinationen ermöglichen Ihrer Anwendung den Zugriff auf und die Arbeit mit Daten aus verschiedenen Quellen über eine einheitliche Schnittstelle, die die "Zusage für einzelne Kopien" von OneLake unterstützt.

Grundlegendes zu Tastenkombinationen in Microsoft Fabric

Tastenkombinationen in Microsoft Fabric bieten eine Möglichkeit, auf Daten in Domänen, Clouds und Konten zuzugreifen, indem eine virtuelle Ansicht von Daten erstellt wird, die sich an verschiedenen Orten befinden. Wenn Sie eine Verknüpfung in Ihrem Arbeitselement erstellen, erstellen Sie einen Verweis auf die Daten, ohne sie physisch zu kopieren, was:

• Reduziert Die Speicherkosten und Die Datenduplizierung
• Stellt die Datenkonsistenz sicher, indem immer auf die Quelldaten verweist
• Vereinfacht den Datenzugriff für Benutzer über einen einheitlichen Namespace.
• Bietet potenzielle Leistungsvorteile durch intelligentes Zwischenspeichern

Verwenden der Verknüpfungserstellungskontrolle

Das Fabric Extensibility Toolkit enthält ein Verknüpfungserstellungssteuerelement, das das Erstellen von Verknüpfungen vereinfacht. Dieses Steuerelement stellt eine standardisierte Benutzeroberfläche für die Verknüpfungserstellung bereit, ähnlich wie bei nativen Fabric-Elementen.

So verwenden Sie das Verknüpfungserstellungssteuerelement in Ihrer Workload:

1. Importieren Sie das Steuerelement aus dem Extensibility Toolkit:

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

2. Fügen Sie das Steuerelement zu Ihrer Komponente hinzu:

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

Programmgesteuertes Erstellen von Verknüpfungen

Wenn Sie Verknüpfungen programmgesteuert erstellen müssen, können Sie die vereinfachte Schnittstelle für die OneLakeShortcutClient Verknüpfungsverwaltung verwenden:

Einrichten des 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);

Erstellen unterschiedlicher Tastenkombinationen

OneLake-Verknüpfungen (von Fabric zu Fabric):

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

Amazon S3-Tastenkombinationen:

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

Azure Data Lake Storage Gen2-Verknüpfungen:

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

Verwalten vorhandener Verknüpfungen

// 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'
);

Verknüpfungstypen und Quellkonfiguration

Ihre Workload kann je nach Anwendungsfall unterschiedliche Tastenkombinationen unterstützen. Der OneLakeShortcutClient bietet Hilfsmethoden für gängige Shortcut-Typen an.

OneLake-Tastenkombinationen (Fabric-Elemente)

OneLake-Verknüpfungen ermöglichen Es Ihrer Workload, auf Daten zuzugreifen, die in anderen Fabric-Elementen wie Lakehouses, KQL-Datenbanken usw. gespeichert sind:

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

Amazon S3-Tastenkombinationen

S3-Shortcuts ermöglichen den Zugriff auf Daten, die in Amazon S3-Buckets gespeichert sind.

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

Arbeiten mit Verknüpfungsdaten

Sobald eine Verknüpfung erstellt wurde, kann Ihre Arbeitslast auf die Daten mithilfe der OneLakeStorageClient zugreifen. Dieser Client bietet Methoden für die Interaktion mit regulären OneLake-Inhalten und Verknüpfungsdaten über eine einheitliche Schnittstelle.

Einrichten des OneLakeStorageClient

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

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

Umgang mit Verknüpfungsmetadaten

Beim Arbeiten mit Verknüpfungen ist es wichtig zu verstehen, dass Verknüpfungsmetadaten und Verknüpfungsinhalte unterschiedlich abgerufen werden:

Abrufen von Verknüpfungsinformationen

Um Informationen zu Verknüpfungen in einem Pfad abzurufen, verwenden Sie getPathMetadata mit 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
})));

Zugriff auf Shortcut-Inhalte

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

Lesen und Schreiben von Shortcut-Daten

Sobald Sie die Verknüpfungsstruktur des Inhalts haben, können Sie Dateien wie gewöhnliche OneLake-Dateien lesen und schreiben.

// 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'
);

Verwendung des Item-Wrappers für vereinfachten Zugriff

Für übersichtlicheren Code können Sie den OneLakeStorageClientItemWrapper verwenden:

// 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');

Vollständiges Beispiel: Arbeiten mit Shortcut-Daten

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

Sicherheitsüberlegungen

Tastenkombinationen respektieren den Sicherheitskontext des Benutzers:

• Für interne Fabric-Quellen (z. B. Lakehouses) wird die Identität des aufrufenden Benutzers verwendet.
• Bei externen Quellen (z. B. S3) werden die während der Verknüpfungserstellung angegebenen Verbindungsanmeldeinformationen verwendet.

Stellen Sie sicher, dass Ihre Arbeitsauslastung die Authentifizierung ordnungsgemäß verarbeitet und geeignete Benutzeroberflächenelemente zum sicheren Eingeben von Verbindungsdetails bereitstellt.

Verwandte Inhalte

• Übersicht über OneLake-Tastenkombinationen
• OneLake-Verknüpfungen REST-APIs
• Wichtige Konzepte im Extensibility Toolkit
• Speichern von Daten in einem Element