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.

SQL-Connector-Typen (fabric-sqlanalytics, fabric-warehouse, und fabric-sqldatabase) verwenden in CLI 1.36.2 standardmäßig die Anwendungsauthentifizierung. Sie greifen auf die Quelle als App-Identität zu, aktuell als Besitzer des App-Elements. Du kannst explizit delegierte Authentifizierung wählen, um stattdessen die Quellberechtigungen jedes angemeldeten Anrufers zu verwenden. Semantische Modelle unterstützen nur delegierte Authentifizierung.

Eine Standard-Warehouse- und Standardmodellkonfiguration sieht wie folgt aus:

connectors:
  - name: inventory
    type: fabric-warehouse
    config:
      workspaceId: "<workspace-id>"
      itemId: "<warehouse-item-id>"
    auth:
      type: application
    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.

Wählen Sie die Quellidentität

Modus	Quellberechtigungen	Wann wird es verwendet?
application	Gewähre der App-Identität Zugriff auf das Quellelement und die erforderlichen SQL-Berechtigungen. App-Nutzer benötigen weiterhin App-Zugriff und Entitätsberechtigungen.	SQL-Connectoren, die app-gesteuerten Zugriff auf freigegebene Quelldaten ermöglichen.
delegated	Jeder Aufrufer benötigt Zugriff auf das Quellelement und die Berechtigung für die angeforderte Operation. Semantische Modellabfragen erfordern die jeweiligen Modellberechtigungen des Aufrufers, einschließlich Build.	Quellautorisierung pro Benutzer oder ein beliebiger Connector für semantische Modelle.

Für delegierten SQL-Zugriff in CLI 1.36.2 setzen Sie auth.type: delegated an diesem Connector in rayfin/rayfin.yml, bevor Sie bereitstellen. CLI-Versionen, deren connector add --help--auth bereitstellt, können sie bei der Erstellung auswählen:

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

Das Flag --auth ist in CLI 1.36.2 nicht verfügbar; verwenden Sie mit dieser Version die YAML-Einstellung. Wenn das Flag unterstützt wird, akzeptiert es application oder delegated nur, wenn der Steckertyp diesen Modus unterstützt. Konfigurieren Sie die Anwendungsauthentifizierung nicht für ein semantisches Modell.

Eine Änderung des Modus gewährt keine Berechtigungen für die Quelle. Entwickler-Anmeldung und Schema-Entdeckung nutzen den Zugriff des Entwicklers und beweisen nicht, dass die bereitgestellte Laufzeit-Identität auf die Quelle zugreifen kann. Bestehende Deklarationen werden nicht automatisch auf den neuen Standard migriert; belassen Sie auth.type explizit. Nach dem erneuten Hinzufügen eines Connectors überprüfen Sie die generierte Konfiguration vor der Bereitstellung.

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.
• Wähle die Quellidentität bewusst. Bei der Anwendungsauthentifizierung erzwingen Sie den Zugriff pro Benutzer über App- und Entitätsberechtigungen, anstatt davon auszugehen, dass Quellberechtigungen für jeden Anrufer überprüft werden. Bei delegierter Authentifizierung sollte auch der Quellenzugriff jedes Anrufers überprüft werden.

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 den erwarteten App-Nutzern und der Laufzeit-Quellidentität. Für die Anwendungsauthentifizierung überprüfen Sie die Quellberechtigungen der App-Identität; für die delegierte Authentifizierung überprüfen Sie die Quellberechtigungen jedes Anrufers.

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