Hubungkan Fabric Apps ke data Fabric

Konektor menyediakan akses yang diketik dari aplikasi Fabric ke data di item Fabric lainnya. Gunakan konektor untuk melakukan query ke lakehouse, gudang, database SQL di Fabric, atau model semantik tanpa mengonfigurasi layanan data terpisah.

Konektor yang didukung

Pilih konektor berdasarkan item Fabric dan operasi yang dibutuhkan aplikasi Anda:

Barang Kain Jenis Konektor Operasi yang Didukung
Titik akhir analisis SQL Lakehouse fabric-sqlanalytics read
warehouse fabric-warehouse read, create, update, dan delete
Basis data SQL dalam Fabric fabric-sqldatabase read, create, update, dan delete
Model semantik fabric-semanticmodel executeQuery

Untuk konektor database gudang dan SQL di Fabric, konfigurasikan hanya operasi yang dibutuhkan aplikasi Anda. Konektor Lakehouse hanya bisa dibaca.

Prasyarat

  • Proyek Fabric Apps yang dibuat dengan npm create @microsoft/rayfin@latest atau diinisialisasi dengan npx rayfin init.
  • Ruang kerja Fabric yang berisi item yang ingin Anda hubungkan.
  • Izin untuk mengakses ruang kerja dan item sumber.
  • ID workspace dan ID item, yang dapat Anda temukan di URL Fabric atau menggunakan perintah pencarian konektor.

Temukan item Fabric

Gunakan connector search untuk mencantumkan item dengan tipe tertentu di workspace. Contoh berikut mencantumkan gudang:

npx rayfin connector search --workspace-id <workspace-id> --type fabric-warehouse --json

Ganti <workspace-id> dengan ID ruang kerja Fabric Anda. Untuk mencari item lain yang didukung, ubah nilainya --type . Anda juga dapat menambahkan filter nama:

npx rayfin connector search "sales" --workspace-id <workspace-id> --type fabric-warehouse --json

Salin ID item dari hasil pencarian.

Tambahkan konektor

Jalankan connector add dari root proyek Fabric Apps Anda. Contoh berikut menambahkan konektor gudang hanya baca yang bernama inventory:

npx rayfin connector add --type fabric-warehouse --workspace-id <workspace-id> --item-id <warehouse-item-id> --name inventory --operations read

Gunakan tipe konektor dan operasi yang sesuai untuk item Fabric lainnya:

# Lakehouse SQL analytics endpoint
npx rayfin connector add --type fabric-sqlanalytics --workspace-id <workspace-id> --item-id <lakehouse-item-id> --name analytics --operations read

# SQL database in Fabric
npx rayfin connector add --type fabric-sqldatabase --workspace-id <workspace-id> --item-id <sql-database-item-id> --name operational --operations read

# Semantic model
npx rayfin connector add --type fabric-semanticmodel --workspace-id <workspace-id> --item-id <semantic-model-item-id> --name salesModel --operations executeQuery

Perintah:

  • Menambahkan konektor ke bagian connectors tingkat atas di rayfin/rayfin.yml.
  • Membuat file konektor di bawah rayfin/connectors/<connector-name>/.
  • Mencetak perintah npm install yang versinya sesuai untuk paket konektor yang diperlukan.

Jalankan perintah instalasi persis yang dicetak oleh CLI. Ini menjaga paket konektor tetap selaras dengan versi CLI Rayfin Anda.

Note

Penemuan skema adalah usaha terbaik. Konektor dapat ditambahkan meskipun penemuan belum selesai. Jika CLI menampilkan peringatan penemuan, selesaikan peringatan tersebut sebelum Anda mendefinisikan entitas dari file metadata.json yang dihasilkan.

Konfigurasi yang dihasilkan menggunakan autentikasi delegasi. Konfigurasi model gudang dan semantik menyerupai contoh berikut:

connectors:
  - name: inventory
    type: fabric-warehouse
    config:
      workspaceId: "<workspace-id>"
      itemId: "<warehouse-item-id>"
    auth:
      type: delegated
    operations:
      - name: read

  - name: salesModel
    type: fabric-semanticmodel
    config:
      workspaceId: "<workspace-id>"
      itemId: "<semantic-model-item-id>"
    auth:
      type: delegated
    version: "1"
    operations:
      - name: executeQuery

Pertahankan nilai model version semantik yang dihasilkan CLI.

Konfigurasikan konektor entitas

Konektor database Lakehouse, gudang, dan SQL menampilkan tabel sumber terpilih sebagai entitas yang diketik. Gunakan file yang dihasilkan metadata.json untuk mendefinisikan hanya tabel dan kolom yang dibutuhkan aplikasi Anda.

Contoh berikut mengasumsikan bahwa gudang yang dipilih berisi dbo.Order tabel dengan kunci utama bilangan bulat bernama OrderID dan kolom teks bernama customerEmail. Ganti nama dan tipe ilustratif ini dengan nilai dari metadata yang Anda hasilkan.

Important

Jangan menyimpulkan kunci utama dari nama kolom. Jika tabel sumber tidak memiliki kunci, hilangkan .primaryKey Entitas tanpa kunci tidak mendukung operasi yang mengakses baris berdasarkan kunci.

Buat entitas:

// rayfin/connectors/inventory/Order.ts
import { entity, int, text, role } from '@microsoft/rayfin-core';
import { Source } from '@microsoft/rayfin-connectors';

@role('authenticated', ['read'])
@entity()
export class Order extends Source({
  schema: 'dbo',
  table: 'Order',
  primaryKey: ['orderId'],
}) {
  @int({ column: 'OrderID' }) orderId!: number;
  @text() customerEmail!: string;
}

Kemudian daftarkan entitas tersebut dalam skema konektor:

// rayfin/connectors/inventory/schema.ts
import type { GraphQLBackedConnector } from '@microsoft/rayfin-connector-fabric-graphql';
import type { ConnectorConfig } from '@microsoft/rayfin-connectors';
import { Order } from './Order.js';

export { Order } from './Order.js';

export const connectorConfig = {
  connector: 'fabric-warehouse',
  operations: ['read'],
  entities: { Order },
} as const satisfies ConnectorConfig;

export type InventorySchema = GraphQLBackedConnector<
  { Order: typeof Order },
  typeof connectorConfig
>;

Jaga agar nama konektor, properti skema, dan nama konfigurasi klien tetap konsisten.

Konfigurasikan klien konektor

Tambahkan skema konektor ke ConnectorsRayfinClient. Konektor model semantik juga memerlukan fabricSemanticModel() runtime:

// src/lib/connectors.ts
import { ConnectorsRayfinClient } from '@microsoft/rayfin-client';
import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';

import {
  connectorConfig as inventoryConfig,
  type InventorySchema,
} from '../../rayfin/connectors/inventory/schema.js';
import {
  connectorConfig as salesModelConfig,
  type SalesModelSchema,
} from '../../rayfin/connectors/salesModel/schema.js';

type AppConnectorsSchema = {
  inventory: InventorySchema;
  salesModel: SalesModelSchema;
};

export const client = new ConnectorsRayfinClient<
  Record<string, never>,
  Record<string, never>,
  AppConnectorsSchema
>(
  {
    baseUrl: '<app-api-url>',
    publishableKey: '<publishable-key>',
    authStorage: true,
    connectors: {
      inventory: inventoryConfig,
      salesModel: salesModelConfig,
    },
  },
  {
    salesModel: fabricSemanticModel(),
  }
);

Gunakan URL API dan kunci yang dapat dipublikasikan dari proyek Fabric Apps Anda. Pertahankan alur masuk aplikasi yang sudah ada. Membuat klien tidak akan membuat pengguna login.

Kueri data yang terhubung

Setelah pengguna masuk, akses konektor entitas melalui nama dan entitasnya:

const orders = await client.connectors.inventory.Order
  .select(['orderId', 'customerEmail'])
  .first(20)
  .execute();

Pilih kolom secara eksplisit dan batasi jumlah baris yang dikembalikan.

Untuk model semantik, kirimkan query DAX dengan executeQuery:

const result = await client.connectors.salesModel.executeQuery({
  query: 'EVALUATE TOPN(10, Sales)',
});

if (result.status === 'success') {
  console.log(result.table.columns, result.table.rows);
} else {
  console.error(result.error.category, result.error.message);
}

Ganti Sales dengan tabel di model semantik Anda. Periksa status yang dikembalikan sebelum Anda menggunakan hasilnya.

Akses konektor aman

Gunakan kontrol ini bersama-sama:

  • Batasi operasi konektor di rayfin.yml hanya untuk tindakan yang diperlukan aplikasi.
  • Tambahkan deklarasi @role ke entitas konektor untuk mengontrol pengguna yang masuk mana yang dapat melakukan setiap operasi.
  • Tambahkan kebijakan tingkat baris atau aturan penyertaan dan pengecualian tingkat kolom saat pengguna hanya memerlukan akses ke sebagian entitas.
  • Biarkan autentikasi terdelegasi tetap aktif agar permintaan konektor menggunakan akses pengguna yang sedang masuk.

Tipe TypeScript sisi klien meningkatkan keamanan pengembangan, tetapi bukan batas otorisasi. Terapkan kontrol akses pada konfigurasi konektor dan peran entitas.

Pasang konektor

Terapkan aplikasi dan konfigurasi konektor:

npx rayfin up

Uji aplikasi yang telah diterapkan menggunakan pengguna yang memiliki izin yang diperlukan baik pada aplikasi Fabric maupun item yang terhubung.

Konten terkait

  • Terakhir diperbarui pada