Collega le app Fabric ai dati Fabric

I connettori forniscono a un'app di Fabric un accesso tipizzato ai dati contenuti in altri elementi di Fabric. Usa un connettore per interrogare un lakehouse, un magazzino, un database SQL in Fabric o un modello semantico senza configurare un servizio dati separato.

Connettori supportati

Scegli un connettore basato sull'elemento Fabric e sulle operazioni di cui la tua app ha bisogno:

Articolo di tessuto	Tipo di connettore	Operazioni supportate
Endpoint di analisi SQL per Lakehouse	`fabric-sqlanalytics`	`read`
warehouse	`fabric-warehouse`	`read`, `create`, `update`e `delete`
Database SQL nell'ambiente Fabric	`fabric-sqldatabase`	`read`, `create`, `update`e `delete`
Modello semantico	`fabric-semanticmodel`	`executeQuery`

Per warehouse e database SQL nei connettori Fabric, configura solo le operazioni di cui la tua app ha bisogno. Il connettore lakehouse è di sola lettura.

Prerequisiti

Progetto app di Fabric creato con npm create @microsoft/rayfin@latest o inizializzato con npx rayfin init.
Uno spazio di lavoro Fabric che contiene l'oggetto a cui vuoi collegarti.
Permesso di accedere allo spazio di lavoro e all'oggetto di origine.
L'ID dello spazio di lavoro e l'ID dell'elemento, che puoi trovare nell'URL di Fabric o tramite il comando di ricerca del connettore.

Trova un elemento di Fabric

Usalo connector search per elencare elementi di un tipo specifico in uno spazio di lavoro. Il seguente esempio elenca i magazzini:

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

Sostituire <workspace-id> con l'ID dell'area di lavoro Fabric. Per cercare un altro oggetto supportato, cambia il --type valore. Puoi anche aggiungere un filtro per il nome:

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

Copia l'ID dell'articolo dal risultato della ricerca.

Aggiungere un connettore

Avvia connector add dalla radice del tuo progetto Fabric Apps. L'esempio seguente aggiunge un connettore del data warehouse di sola lettura denominato inventory:

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

Usa il tipo di connettore corrispondente e le operazioni per gli altri elementi di 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

Il comando :

Aggiunge il connettore alla sezione superiore connectors in rayfin/rayfin.yml.
Crea i file di connettore sotto rayfin/connectors/<connector-name>/.
Stampa un comando npm install con versione corrispondente per i pacchetti dei connettori richiesti.

Esegui il comando di installazione esatto stampato dalla CLI. Questo mantiene i pacchetti dei connettori allineati con la versione di Rayfin CLI.

Annotazioni

La scoperta dello schema è il miglior tentativo. Il connettore può essere aggiunto anche se la scoperta non viene completata. Se la CLI mostra un avviso di discovery, risolvilo prima di definire entità dal file generato metadata.json .

La configurazione generata utilizza l'autenticazione delegata. Una configurazione di magazzino e modello semantico somiglia al seguente esempio:

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

Mantenere il valore semantico del modello version generato dalla CLI.

Configura un connettore di entità

I connettori per lakehouse, data warehouse e database SQL espongono le tabelle di origine selezionate come entità tipizzate. Usa il file generato metadata.json per definire solo le tabelle e le colonne di cui la tua app ha bisogno.

Il seguente esempio assume che il warehouse selezionato contenga una dbo.Order tabella con una chiave primaria intera chiamata OrderID e una colonna di testo denominata customerEmail. Sostituisci questi nomi e tipi illustrativi con valori provenienti dai tuoi metadati generati.

Important

Non dedurre una chiave primaria dal nome di una colonna. Se una tabella sorgente non ha una chiave, ometti primaryKey. Le entità senza chiave non supportano operazioni che individuano una riga tramite chiave.

Crea l'entità:

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

Poi registra l'entità nello schema del connettore:

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

Mantieni coerenti il nome del connettore, la proprietà dello schema e il nome della configurazione del client.

Configura il client dei connettori

Aggiungi gli schemi dei connettori a ConnectorsRayfinClient. I connettori per modelli semantici richiedono anche il 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(),
  }
);

Usa l'URL API e la chiave pubblicabile dal tuo progetto Fabric Apps. Mantieni il flusso di accesso esistente dell'app. La creazione del client non comporta l'accesso di un utente.

Interroga i dati collegati

Dopo che l'utente ha effettuato l'accesso, accedere a un connettore di entità tramite il nome e l'entità:

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

Seleziona esplicitamente le colonne e limita il numero di righe restituite.

Per un modello semantico, invia una query DAX con 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);
}

Sostituisci Sales con una tabella nel tuo modello semantico. Controlla lo stato restituito prima di utilizzare il risultato.

Accesso sicuro al connettore

Usa questi controlli insieme:

Limita le operazioni del connettore in rayfin.yml alle azioni necessarie all'app.
Aggiungi dichiarazioni @role nelle entità del connettore per controllare quali utenti che hanno effettuato l'accesso possono eseguire ciascuna operazione.
Aggiungi criteri a livello di riga o regole di inclusione ed esclusione dei campi quando gli utenti devono accedere solo a una parte di un'entità.
Mantieni abilitata l'autenticazione delegata così che le richieste di connettore utilizzino l'accesso dell'utente connesso.

I tipi TypeScript lato client migliorano la sicurezza dello sviluppo, ma non rappresentano un limite di autorizzazione. Applicare il controllo di accesso nella configurazione del connettore e nei ruoli dell'entità.

Distribuire il connettore

Distribuisci l'app e la configurazione del connettore:

npx rayfin up

Testa l'app distribuita con un utente che abbia i permessi attesi sia sull'app Fabric che sull'elemento collegato.

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-09-29