Sdílet prostřednictvím

Návod: Vytvoření zástupců ve vaší položce

Tento článek vysvětluje, jak implementovat funkce zástupce v položce úlohy Microsoft Fabric pro odkazování na data z lakehouses nebo externích cloudových úložišť, jako je Amazon S3, aniž byste museli kopírovat data. Klávesové zkratky umožňují vaší aplikaci přistupovat k datům z různých zdrojů a pracovat s daty z různých zdrojů prostřednictvím sjednoceného rozhraní, které podporuje "příslib jedné kopie" OneLake.

Pochopení zkratek v Microsoft Fabric

Klávesové zkratky v Microsoft Fabric umožňují přístup k datům napříč doménami, cloudy a účty vytvořením virtuálního zobrazení dat umístěných v různých umístěních. Při vytváření zástupce v položce úlohy vytváříte odkaz na data bez fyzického kopírování, což:

  • Snižuje náklady na úložiště a duplikaci dat.
  • Zajišťuje konzistenci dat tím, že vždy odkazuje na zdrojová data.
  • Zjednodušuje přístup k datům pro uživatele prostřednictvím jednotného oboru názvů.
  • Poskytuje potenciální výhody výkonu prostřednictvím inteligentního ukládání do mezipaměti.

Použití ovládacího prvku Pro vytvoření zástupce

"Sada nástrojů pro rozšiřitelnost Fabric obsahuje ovládací prvek pro vytvoření zástupce, který zjednodušuje proces jeho vytváření." Tento ovládací prvek poskytuje standardizované uživatelské rozhraní pro vytváření zástupců, podobně jako zkušenost s nativními prvky v rámci Fabricu.

Použití ovládacího prvku Vytvoření zástupce v úloze:

  1. Importujte ovládací prvek ze sady Nástrojů rozšiřitelnosti:

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

  2. Přidejte ovládací prvek do komponenty:

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

Vytváření zástupců programově

Pokud potřebujete vytvořit zástupce programově, můžete použít OneLakeShortcutClient, které poskytuje zjednodušené rozhraní pro správu zástupců.

Nastavení 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);

Vytváření různých typů klávesových zkratek

Zkratky OneLake (Fabric to 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
);

Klávesové zkratky 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
);

Klávesové zkratky 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
);

Správa existujících zástupců

// 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 zkratek a konfigurace zdroje

Vaše úloha může podporovat různé typy klávesových zkratek v závislosti na vašem případu použití. OneLakeShortcutClient poskytuje pomocné metody pro běžné typy klávesových zkratek:

Klávesové zkratky OneLake (položky prostředků infrastruktury)

Klávesové zkratky OneLake umožňují vaší úloze přistupovat k datům uloženým v jiných položkách infrastruktury, jako jsou Lakehouses, databáze KQL atd.:

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

Klávesové zkratky Amazon S3

Klávesové zkratky S3 umožňují přístup k datům uloženým v kontejnerech 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
);

Práce s daty zkratek

Po vytvoření zástupce může vaše úloha pracovat s daty pomocí nástroje OneLakeStorageClient. Tento klient poskytuje metody pro interakci se standardním obsahem OneLake a zkratkovými daty prostřednictvím sjednoceného rozhraní.

Nastavení klienta úložiště OneLake

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

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

Práce s metadaty zástupců (odkazů)

Při práci s klávesovými zkratkami je důležité pochopit, že metadata zástupců a obsah zástupce se načítají jinak:

Získání informací o zkratce

Informace o klávesových zkratkách v cestě získáte pomocí příkazu getPathMetadatashortcutMetadata: 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
})));

Přístup k obsahu zkratky

Důležité

Pokud shortcutMetadata: true získáte pouze informace o samotné zkratce, nikoli o obsahu uvnitř zkratky. Pokud chcete získat přístup k skutečným datům v rámci zástupce, musíte provést samostatné volání pomocí cesty zástupce:

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

Čtení a zápis dat zástupce/klávesové zkratky

Jakmile máte strukturu obsahu zástupce, můžete číst a zapisovat soubory stejně jako běžné soubory 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'
);

Použití obálky položek pro zjednodušený přístup

Pro čistější kód můžete použít 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');

Kompletní příklad: Práce s daty shortcutu

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

Bezpečnostní aspekty

Klávesové zkratky respektují kontext zabezpečení uživatele:

  • Pro interní zdroje infrastruktury (například Lakehouses) se používá identita volajícího uživatele.
  • Pro externí zdroje (například S3) se použijí údaje pro připojení zadané při vytváření zástupce.

Ujistěte se, že vaše úloha správně zpracovává ověřování a poskytuje příslušné prvky uživatelského rozhraní pro bezpečné zadávání podrobností o připojení.

Související obsah

  • Last updated on