操作指南：在您的项目中创建快捷方式

本文介绍如何在 Microsoft Fabric 工作负荷项中实现快捷方式功能，以引用来自 Lakehouses 或外部云存储源（如 Amazon S3）的数据，而无需复制数据。快捷方式允许应用程序通过统一接口访问和处理来自各种源的数据，从而支持 OneLake 的“单一复制承诺”。

了解 Microsoft Fabric 中的快捷方式

Microsoft Fabric 中的快捷方式通过创建驻留在不同位置的数据的虚拟视图，提供跨域、云和帐户访问数据的方法。在工作负荷项中创建快捷方式时，需要创建对数据的引用，而无需以物理方式复制数据，这会：

降低存储成本和重复数据
始终指向源数据来确保数据一致性
通过统一命名空间简化用户的数据访问
通过智能缓存提供潜在的性能优势

快捷方式创建控件的使用

Fabric 扩展性工具包包括一个快捷方式创建控件，用于简化创建快捷方式的过程。此控件提供一个标准化的用户界面，用于创建快捷方式，类似于在原生 Fabric 项目上的体验。

若要在工作负荷中使用快捷方式创建控件，请执行以下命令：

从 Extensibility Toolkit 导入控件：

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

将控件添加到组件：

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

以编程方式创建快捷方式

如果需要以编程方式创建快捷方式，可以使用 OneLakeShortcutClient 它为快捷方式管理提供简化的界面：

设置 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);

创建不同类型的快捷方式

OneLake 快捷方式（Fabric 到 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 快捷方式：

// 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 快捷方式：

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

管理现有快捷方式

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

快捷方式类型和源配置

工作负荷可以支持不同类型的快捷方式，具体取决于用例。为 OneLakeShortcutClient 常见快捷类型提供帮助程序方法：

OneLake 快捷方式（Fabric 项目）

OneLake 快捷方式允许您的任务访问存储在其他 Fabric 项目（如 Lakehouses、KQL 数据库等）中的数据：

// 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 快捷方式

S3 快捷方式允许访问 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
);

使用快捷数据

创建快捷方式后，工作负载可以使用该快捷方式 OneLakeStorageClient处理数据。此客户端提供通过统一接口与常规 OneLake 内容和快捷数据进行交互的方法。

配置 OneLakeStorageClient

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

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

使用快捷方式元数据

使用快捷方式时，请务必了解以不同的方式检索快捷方式元数据和快捷方式内容：

获取快捷方式信息

若要获取有关路径中的快捷方式的信息，请使用 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
})));

访问快捷方式内容

重要

当 shortcutMetadata: true，你仅获取有关快捷方式本身的信息，而不是快捷方式内的内容。若要访问快捷方式内的实际数据，需要使用快捷方式的路径进行单独的调用：

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

读取和写入快捷方式数据

获得快捷方式内容结构后，可以像常规 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'
);

使用项目包以简化访问

对于更简洁的代码，可以使用 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');

完整示例：使用快捷数据

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

安全注意事项

快捷方式遵循用户的安全上下文：

对于 Fabric 内部源（如 Lakehouses），将使用调用用户的标识
对于外部源（如 S3），使用在创建快捷方式期间指定的连接凭据

确保工作负荷正确处理身份验证，并提供适当的用户界面元素，以便安全地输入连接详细信息。

反馈

此页面是否有帮助？

Last updated on 2025-09-17