Verbinden Sie Fabric-Apps mit Fabric-Daten

Connectors ermöglichen einen getippten Zugriff von einer Fabric-App auf Daten in anderen Fabric-Elementen. Verwenden Sie einen Connector, um ein Seehaus, Lager, eine SQL-Datenbank in Fabric oder einem semantischen Modell abzufragen, ohne einen separaten Datendienst zu konfigurieren.

Unterstützte Anschlüsse

Wählen Sie einen Connector basierend auf dem Fabric-Element und den Operationen, die Ihre App benötigt:

Gewebe-Element	Konnektortyp	Unterstützte Operationen
Lakehouse-SQL-Analyseendpunkt	fabric-sqlanalytics	read
warehouse	fabric-warehouse	read, create, update und delete
SQL-Datenbank in Fabric	fabric-sqldatabase	read, create, update und delete
Semantikmodell	fabric-semanticmodel	executeQuery

Für Warehouse- und SQL-Datenbank-in-Fabric-Connectoren konfigurieren Sie nur die Operationen, die Ihre App benötigt. Der Lakehouse-Konnektor ist schreibgeschützt.

Voraussetzungen

• Ein Fabric Apps-Projekt, das mit npm create @microsoft/rayfin@latest erstellt oder mit npx rayfin init initialisiert wurde.
• Ein Fabric-Arbeitsbereich, der den Gegenstand enthält, mit dem Sie verbunden werden möchten.
• Berechtigung zum Zugriff auf den Arbeitsbereich und das Quellobjekt.
• Die Arbeitsbereichs-ID und die Item-ID, die Sie in der Fabric-URL oder mit dem Connector-Suchbefehl finden können.

Finde einen Fabric-Artikel

Verwenden connector search Sie es, um Elemente eines bestimmten Typs in einem Arbeitsbereich aufzulisten. Das folgende Beispiel listet Lagerhäuser auf:

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

Ersetzen Sie <workspace-id> durch Ihre Fabric-Arbeitsbereichs-ID. Um nach einem anderen unterstützten Element zu suchen, ändere den --type Wert. Du kannst auch einen Namensfilter hinzufügen:

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

Kopiere die Artikel-ID aus dem Suchergebnis.

Hinzufügen eines Connectors

Starte connector add vom Kern deines Fabric Apps-Projekts aus. Das folgende Beispiel fügt einen schreibgeschützten Warehouse-Connector mit dem Namen inventoryhinzu:

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

Verwenden Sie den entsprechenden Steckertyp und die Operationen für andere Fabric-Artikel:

# 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

Der Befehl:

• Fügt den Konnektor zum Abschnitt auf oberster Ebene connectors in rayfin/rayfin.yml hinzu.
• Erstellt die Connector-Dateien unter rayfin/connectors/<connector-name>/.
• Druckt einen versionsangepassten npm install Befehl für die erforderlichen Connector-Pakete.

Führe genau den Installationsbefehl aus, der von der CLI ausgedruckt wird. Dadurch bleiben die Connector-Pakete mit deiner Rayfin-CLI-Version synchron.

Hinweis

Schema-Entdeckung ist die beste Anstrengung. Der Konnektor kann auch dann hinzugefügt werden, wenn die Erkennung nicht abgeschlossen ist. Wenn die CLI eine Discovery-Warnung anzeigt, lösen Sie diese auf, bevor Sie Entitäten aus der generierten metadata.json Datei definieren.

Die generierte Konfiguration verwendet delegierte Authentifizierung. Eine Lagerhaus- und semantisches Modell-Konfiguration ähnelt folgendem Beispiel:

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

Behalten Sie den semantischen Modellwert version , den die CLI generiert.

Konfigurieren Sie einen Entitätskonnektor

Lakehouse-, Warehouse- und SQL-Datenbank-Connectoren stellen ausgewählte Quelltabellen als typisierte Entitäten bereit. Verwenden Sie die generierte metadata.json Datei, um nur die Tabellen und Spalten zu definieren, die Ihre App benötigt.

Das folgende Beispiel geht davon aus, dass das ausgewählte Warehouse eine Tabelle dbo.Order mit einem ganzzahligen Primärschlüssel namens OrderID und einer Textspalte namens customerEmail enthält. Ersetzen Sie diese illustrativen Namen und Typen durch Werte aus Ihren generierten Metadaten.

Important

Leiten Sie keinen Primärschlüssel aus einem Spaltennamen ab. Wenn eine Quelltabelle keinen Schlüssel hat, lasse primaryKey. Schlüssellose Entitäten unterstützen keine Operationen, die über den Schlüssel auf eine Zeile zugreifen.

Erstellen Sie die Entität:

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

Registrieren Sie dann die Entität im Connector-Schema:

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

Halten Sie den Connector-Namen, die Schema-Eigenschaft und den Client-Konfigurationsnamen konsistent.

Konfigurieren Sie den Connectors-Client

Füge die Connector-Schemata zu ConnectorsRayfinClient hinzu. Semantische Modellverbinder benötigen ebenfalls die Laufzeit 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(),
  }
);

Verwenden Sie die API-URL und den publizierbaren Schlüssel aus Ihrem Fabric Apps-Projekt. Beibehalten Sie den bestehenden Anmeldefluss der App. Durch das Erstellen eines Clients wird kein Benutzer angemeldet.

Verbundene Daten abfragen

Nachdem der Benutzer sich eingeloggt hat, greifen Sie über seinen Namen und die Entität auf einen Entitäts-Connector zu:

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

Wähle explizit Spalten aus und begrenzte die Anzahl der zurückgegebenen Zeilen.

Für ein semantisches Modell senden Sie eine DAX-Abfrage mit 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);
}

Ersetzen Sie Sales durch eine Tabelle in Ihrem semantischen Modell. Überprüfen Sie den zurückgegebenen Status, bevor Sie das Ergebnis verwenden.

Sicherer Verbindungszugang

Verwenden Sie diese Steuerungen zusammen:

• Beschränke die Operationen des Connectors in rayfin.yml auf die Aktionen, die die App benötigt.
• Fügen Sie @role Deklarationen zu Konnektorentitäten hinzu, um zu steuern, welche angemeldeten Benutzer die jeweilige Operation ausführen können.
• Fügen Sie Zeilenrichtlinien oder Ein-/Ausschlussregeln für Felder hinzu, wenn Benutzer nur auf einen Teil einer Entität zugreifen müssen.
• Halte delegierte Authentifizierung aktiviert, damit Connector-Anfragen den Zugriff des angemeldeten Nutzers nutzen.

Clientseitige TypeScript-Typen verbessern die Entwicklungssicherheit, aber sie sind keine Autorisierungsgrenze. Erzwingen Sie den Zugriff in der Connector-Konfiguration und in den Entitätsrollen.

Bereitstellen des Connectors

Bereite die App- und Connector-Konfiguration aus:

npx rayfin up

Teste die bereitgestellte App mit einem Nutzer, der sowohl für die Fabric-App als auch für das verbundene Gerät die erwarteten Berechtigungen hat.

Verwandte Inhalte

• Erstellen Sie eine App, die mit einem semantischen Modell verbunden ist
• Definieren von Datenmodellen
• Definieren von Datenberechtigungen
• Authentifizierung für Fabric-Apps
• Eine Fabric-App in Fabric bereitstellen
• Rayfin CLI-Referenz