เชื่อมต่อแอป Fabric กับข้อมูล Fabric

ตัวเชื่อมต่อให้การเข้าถึงแบบพิมพ์จากแอป Fabric ไปยังข้อมูลในรายการ Fabric อื่น ๆ ใช้ตัวเชื่อมต่อเพื่อสืบค้นบ้านทะเลสาบ คลังสินค้า ฐานข้อมูล SQL ใน Fabric หรือโมเดลเชิงความหมายโดยไม่ต้องตั้งค่าบริการข้อมูลแยกต่างหาก

ตัวเชื่อมต่อที่รองรับ

เลือกตัวเชื่อมต่อตามรายการและการดําเนินการใน Fabric ที่แอปของคุณต้องการ:

รายการผ้า	ชนิดตัวเชื่อมต่อ	การดำเนินการที่รองรับ
จุดสิ้นสุดการวิเคราะห์ของ Lakehouse SQL	fabric-sqlanalytics	read
โกดัง	fabric-warehouse	read, create, updateและ delete
ฐานข้อมูล SQL ใน Fabric	fabric-sqldatabase	read, create, updateและ delete
แบบจําลองแสดงความหมาย	fabric-semanticmodel	executeQuery

สําหรับคลังสินค้าและฐานข้อมูล SQL ในตัวเชื่อมต่อ Fabric ให้กําหนดค่าเฉพาะการดําเนินการที่แอปของคุณต้องการเท่านั้น ตัวเชื่อมต่อ Lakehouse เป็นแบบอ่านอย่างเดียว

ข้อกําหนดเบื้องต้น

• โปรเจ็กต์ Fabric Apps ที่สร้างด้วย npm create @microsoft/rayfin@latest หรือเริ่มต้นด้วย npx rayfin init
• พื้นที่ทํางาน Fabric ที่มีรายการที่คุณต้องการเชื่อมต่อ
• สิทธิ์ในการเข้าถึงพื้นที่ทํางานและรายการต้นทาง
• รหัสพื้นที่ทํางานและรหัสรายการ ซึ่งคุณสามารถค้นหาได้ใน URL Fabric หรือโดยใช้คําสั่งค้นหาตัวเชื่อมต่อ

ค้นหาสินค้า Fabric

ใช้เพื่อ connector search แสดงรายการรายการประเภทเฉพาะในพื้นที่ทํางาน ตัวอย่างต่อไปนี้แสดงรายการคลังสินค้า:

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

แทนที่ <workspace-id> ด้วยรหัสพื้นที่ทํางาน Fabric ของคุณ หากต้องการค้นหารายการที่รองรับอื่น ให้เปลี่ยน --type ค่า คุณยังสามารถเพิ่มตัวกรองชื่อได้ด้วย:

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

คัดลอกรหัสรายการจากผลการค้นหา

เพิ่มตัวเชื่อมต่อ

เริ่มต้นconnector addจากรากฐานของโปรเจกต์ Fabric Apps ของคุณ ตัวอย่างต่อไปนี้เพิ่มตัวเชื่อมต่อคลังข้อมูลแบบอ่านอย่างเดียวชื่อ inventory:

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

ใช้ประเภทขั้วต่อและการดําเนินการที่สอดคล้องกันสําหรับรายการ Fabric อื่น ๆ:

# 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

คําสั่ง:

• เพิ่มตัวเชื่อมต่อไปยังส่วนระดับ connectors บนสุดใน rayfin/rayfin.yml.
• สร้างไฟล์คอนเนคทีเรียภายใต้ rayfin/connectors/<connector-name>/.
• พิมพ์คําสั่งที่ตรงกับ npm install เวอร์ชันสําหรับแพ็กเกจตัวเชื่อมต่อที่ต้องการ

รันคําสั่งติดตั้งที่พิมพ์โดย CLI อย่างแม่นยํา สิ่งนี้ช่วยให้แพ็กเกจตัวเชื่อมต่อสอดคล้องกับเวอร์ชัน Rayfin CLI ของคุณ

Note

การค้นหาสคีมาคือความพยายามที่ดีที่สุด สามารถเพิ่มตัวเชื่อมต่อได้แม้ว่าการค้นหาจะไม่เสร็จสมบูรณ์ หาก CLI แสดงคําเตือนการค้นหา ให้แก้ไขก่อนกําหนดเอนทิตีจากไฟล์ที่สร้างขึ้นmetadata.json

การกําหนดค่าที่สร้างขึ้นใช้การตรวจสอบสิทธิ์แบบมอบหมาย การกําหนดค่าคลังสินค้าและโมเดลเชิงความหมายมีลักษณะคล้ายกับตัวอย่างต่อไปนี้:

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

เก็บค่าโมเดล version เชิงความหมายที่ CLI สร้างขึ้นไว้

กําหนดค่าตัวเชื่อมต่อเอนทิตี

ตัวเชื่อมต่อฐานข้อมูล Lakehouse, warehouse และ SQL จะเปิดเผยตารางต้นทางที่เลือกเป็นเอนทิตีที่มีชนิดข้อมูล ใช้ไฟล์ที่สร้างขึ้น metadata.json เพื่อกําหนดเฉพาะตารางและคอลัมน์ที่แอปของคุณต้องการเท่านั้น

ตัวอย่างต่อไปนี้สมมติว่าคลังข้อมูลที่เลือกมีdbo.Orderตารางที่มีคีย์OrderIDหลักเป็นจํานวนเต็มชื่อและคอลัมน์ข้อความชื่อcustomerEmail แทนที่ชื่อและประเภทตัวอย่างเหล่านี้ด้วยค่าจากเมตาดาต้าที่คุณสร้างขึ้น

Important

อย่าอนุมานคีย์หลักจากชื่อคอลัมน์ ถ้าตารางซอร์สโค้ดไม่มีคีย์ ให้ละเว้นprimaryKey สิ่งมีชีวิตแบบไม่มีคีย์ไม่รองรับการดําเนินการที่จัดการแถวด้วยคีย์

สร้างเอนทิตี:

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

จากนั้นลงทะเบียนเอนทิตีในสคีมาของตัวเชื่อมต่อ:

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

รักษาชื่อคอนเนคเตอร์ คุณสมบัติสคีมา และชื่อการกําหนดค่าไคลเอนต์ให้สอดคล้องกัน

กําหนดค่าไคลเอนต์ของตัวเชื่อมต่อ

เพิ่มสคีมาของตัวเชื่อมต่อลงใน ConnectorsRayfinClient. ตัวเชื่อมต่อโมเดลเชิงความหมายยังต้องการ fabricSemanticModel() เวลารันไทม์:

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

ใช้ URL API และคีย์ที่เผยแพร่ได้จากโปรเจกต์ Fabric Apps ของคุณ รักษากระบวนการเข้าสู่ระบบที่มีอยู่ของแอปไว้ การสร้างไคลเอนต์ไม่ได้ทําให้ผู้ใช้ลงชื่อเข้าใช้

ค้นหาข้อมูลที่เชื่อมต่อ

หลังจากผู้ใช้ลงชื่อเข้าใช้แล้ว ให้เข้าถึงตัวเชื่อมต่อเอนทิตีผ่านชื่อและเอนทิตีของมัน:

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

เลือกคอลัมน์อย่างชัดเจนและจํากัดจํานวนแถวที่คืนค่า

สําหรับโมเดลเชิงความหมาย ให้ส่งคําค้น DAX พร้อมกับ 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);
}

แทนที่ Sales ด้วยตารางในโมเดลความหมายของคุณ ตรวจสอบสถานะการส่งคืนก่อนใช้ผลลัพธ์

การเข้าถึงตัวเชื่อมต่อที่ปลอดภัย

ใช้คอนโทรลเหล่านี้ร่วมกัน:

• จํากัดการทํางานของตัวเชื่อมต่อให้ rayfin.yml อยู่ในขอบเขตของการกระทําที่แอปต้องการ
• เพิ่ม @role การประกาศให้กับเอนทิตีของตัวเชื่อมต่อเพื่อควบคุมว่าผู้ใช้ที่ลงชื่อเข้าใช้สามารถดําเนินการแต่ละขั้นตอนได้เพียงใด
• เพิ่มนโยบายแถวหรือฟิลด์รวมและยกเว้นกฎเมื่อผู้ใช้ต้องการเข้าถึงเพียงบางส่วนของเอนทิตี
• เปิดใช้งานการตรวจสอบสิทธิ์ที่ได้รับมอบหมายไว้ เพื่อให้คําขอเชื่อมต่อใช้สิทธิ์ของผู้ใช้ที่ลงชื่อเข้าใช้

ประเภท TypeScript ฝั่งไคลเอนต์ช่วยเพิ่มความปลอดภัยในการพัฒนา แต่ไม่ใช่ขอบเขตการอนุญาต บังคับใช้การเข้าถึงในบทบาทการกําหนดค่าตัวเชื่อมต่อและเอนทิตี

ปรับใช้ตัวเชื่อมต่อ

ปรับใช้การตั้งค่าแอปและตัวเชื่อมต่อ:

npx rayfin up

ทดสอบแอปที่ติดตั้งกับผู้ใช้ที่มีสิทธิ์ตามที่คาดหวังทั้งในแอป Fabric และรายการที่เชื่อมต่อ

เนื้อหาที่เกี่ยวข้อง

• สร้างแอปที่เชื่อมต่อกับโมเดลเชิงความหมาย
• กําหนดแบบจําลองข้อมูล
• กําหนดสิทธิ์ของข้อมูล
• การยืนยันตัวตนสําหรับแอป Fabric
• ปรับใช้แอป Fabric เป็น Fabric
• การอ้างอิง Rayfin CLI