방법: 항목에 바로 가기 만들기

이 문서에서는 데이터를 복사하지 않고 Lakehouse 또는 Amazon S3 같은 외부 클라우드 스토리지 원본의 데이터를 참조하도록 Microsoft Fabric 워크로드 항목에서 바로 가기 기능을 구현하는 방법을 설명합니다. 바로 가기를 사용하면 애플리케이션이 통합 인터페이스를 통해 다양한 원본의 데이터에 액세스하고 작업할 수 있으며 OneLake의 "단일 복사 약속"을 지원합니다.

Microsoft Fabric의 바로 가기 이해

Microsoft Fabric의 바로 가기는 다른 위치에 있는 데이터의 가상 보기를 만들어 도메인, 클라우드 및 계정 간에 데이터에 액세스하는 방법을 제공합니다. 워크로드 항목에 바로 가기를 만들면 데이터를 물리적으로 복사하지 않고 데이터에 대한 참조가 생성됩니다.

스토리지 비용 및 데이터 중복 감소
항상 원본 데이터를 가리켜 데이터 일관성을 보장합니다.
통합 네임스페이스를 통해 사용자의 데이터 액세스를 간소화합니다.
지능형 캐싱을 통해 잠재적인 성능 이점 제공

바로 가기 만들기 컨트롤 사용

패브릭 확장성 도구 키트에는 바로 가기를 만드는 프로세스를 간소화하는 바로 가기 만들기 컨트롤이 포함되어 있습니다. 이 컨트롤은 네이티브 패브릭 항목의 환경과 유사하게 바로 가기를 만들기 위한 표준화된 사용자 인터페이스를 제공합니다.

워크로드에서 바로 가기 만들기 컨트롤을 사용하려면 다음을 수행합니다.

확장성 도구 키트에서 컨트롤을 가져옵니다.

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 바로 가기(패브릭에서 패브릭으로):

// 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 바로 가기(패브릭 항목)

OneLake 바로 가기를 사용하면 워크로드가 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)의 경우 호출 사용자의 ID가 사용됩니다.
외부 원본(예: S3)의 경우 바로 가기를 만드는 동안 지정된 연결 자격 증명이 사용됩니다.

워크로드가 인증을 올바르게 처리하고 연결 세부 정보를 안전하게 입력하기 위한 적절한 사용자 인터페이스 요소를 제공하는지 확인합니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-12-15