Conecta aplicaciones de Fabric a datos de Fabric

Los conectores proporcionan acceso tipado desde una aplicación de Fabric a los datos de otros elementos de Fabric. Utiliza un conector para consultar un lago de datos, almacén, base de datos SQL en Fabric o un modelo semántico sin configurar un servicio de datos separado.

Conectores compatibles

Elige un conector basado en el elemento Fabric y las operaciones que necesite tu app:

Elemento de tela Tipo de conector Operaciones soportadas
Punto de conexión de análisis SQL de almacén de lago fabric-sqlanalytics read
warehouse fabric-warehouse read, create, update y delete.
Base de datos SQL en Fabric fabric-sqldatabase read, create, update y delete.
Modelo semántico fabric-semanticmodel executeQuery

Para almacén y base de datos SQL en conectores Fabric, configura solo las operaciones que necesite tu aplicación. El conector de lakehouse es de solo lectura.

Prerequisites

  • Un proyecto Fabric Apps creado con npm create @microsoft/rayfin@latest o inicializado con npx rayfin init.
  • Un espacio de trabajo Fabric que contiene el elemento al que quieres conectarte.
  • Permiso para acceder al espacio de trabajo y al elemento de origen.
  • El ID del espacio de trabajo y el ID del elemento, que puedes encontrar en la URL de Fabric o usando el comando de búsqueda de conectores.

Encuentra un artículo de Fabric

Úsalo connector search para listar elementos de un tipo específico en un espacio de trabajo. El siguiente ejemplo enumera almacenes:

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

Reemplace por <workspace-id> el identificador del área de trabajo de Fabric. Para buscar otro artículo compatible, cambia su --type valor. También puedes añadir un filtro de nombres:

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

Copia el ID del artículo desde el resultado de búsqueda.

Adición de un conector

Ejecuta connector add desde la raíz de tu proyecto de Fabric Apps. El siguiente ejemplo añade un conector de almacén de solo lectura llamado inventory:

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

Utiliza el tipo de conector y las operaciones correspondientes para otros elementos 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

El comando:

  • Añade el conector a la sección de nivel superior connectors en rayfin/rayfin.yml.
  • Crea los archivos de conector bajo rayfin/connectors/<connector-name>/.
  • Imprime un comando de npm install versión compatible para los paquetes de conectores requeridos.

Ejecuta el comando de instalación exacto que imprime la CLI. Esto mantiene los paquetes de conectores alineados con la versión de la CLI de Rayfin.

Nota:

El descubrimiento de esquemas es el mejor esfuerzo. El conector se puede añadir incluso si el descubrimiento no se completa. Si la CLI muestra una advertencia de descubrimiento, resuélvela antes de definir entidades a partir del archivo generado metadata.json .

La configuración generada utiliza autenticación delegada. Una configuración de almacén y modelo semántico se asemeja al siguiente ejemplo:

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

Mantén el valor del modelo version semántico que genera la COLI.

Configurar un conector de entidad

Los conectores Lakehouse, almacén y base de datos SQL exponen tablas de origen seleccionadas como entidades tipadas. Usa el archivo generado metadata.json para definir solo las tablas y columnas que tu aplicación necesita.

El siguiente ejemplo asume que el almacén seleccionado contiene una dbo.Order tabla con una clave primaria entera llamada OrderID y una columna de texto llamada customerEmail. Sustituye estos nombres y tipos ilustrativos por valores de los metadatos generados por ti.

Important

No infieras una clave primaria a partir del nombre de una columna. Si una tabla fuente no tiene clave, omite primaryKey. Las entidades sin clave no admiten operaciones que seleccionan una fila mediante una clave.

Crea la entidad:

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

Luego se registra la entidad en el esquema del conector:

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

Mantén el nombre del conector, la propiedad del esquema y el nombre de configuración del cliente consistentes.

Configurar el cliente de conectores

Añade los esquemas de conectores a ConnectorsRayfinClient. Los conectores de modelos semánticos también requieren el fabricSemanticModel() tiempo de ejecución:

// 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 la URL de la API y la clave publicable de tu proyecto Fabric Apps. Mantén el flujo de inicio de sesión existente en la app. La creación del cliente no inicia la sesión de un usuario.

Consulta datos conectados

Después de que el usuario inicie sesión, accede a un conector de entidad mediante su nombre y su entidad:

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

Selecciona columnas explícitamente y limita el número de filas devueltas.

Para un modelo semántico, envía una consulta 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);
}

Sustituye Sales por una tabla en tu modelo semántico. Comprueba el estado devuelto antes de usar el resultado.

Acceso seguro por conector

Utiliza estos controles juntos:

  • Limita las operaciones del conector en rayfin.yml a las acciones que la aplicación necesita.
  • Añadir declaraciones de @role a las entidades de conector para controlar qué usuarios con sesión iniciada pueden realizar cada operación.
  • Añadir políticas de fila o reglas de inclusión y exclusión de campos cuando los usuarios solo necesitan acceso a una parte de una entidad.
  • Mantén activada la autenticación delegada para que las solicitudes de conector utilicen el acceso del usuario iniciado sesión.

Los tipos TypeScript del lado del cliente mejoran la seguridad del desarrollo, pero no constituyen un límite de autorización. Aplicar el control de acceso en la configuración del conector y en los roles de la entidad.

Desplegar el conector

Despliega la aplicación y la configuración del conector:

npx rayfin up

Prueba la aplicación desplegada con un usuario que tenga los permisos esperados tanto en la app de Fabric como en el elemento conectado.

Contenido relacionado

  • Última actualización el