Conecte aplicativos Fabric aos dados Fabric

Conectores fornecem acesso tipado de um aplicativo do Fabric a dados em outros itens do Fabric. Use um conector para consultar um lakehouse, um data warehouse, um banco de dados SQL no Fabric ou um modelo semântico sem configurar um serviço de dados separado.

Conectores suportados

Escolha um conector baseado no item Fabric e nas operações que seu app precisa:

Para data warehouse e banco de dados SQL nos conectores do Fabric, configure apenas as operações de que seu aplicativo precisa. O conector da casa do lago é somente leitura.

Pré-requisitos

• Um projeto Fabric Apps criado com npm create @microsoft/rayfin@latest ou inicializado com npx rayfin init.
• Um espaço de trabalho Fabric que contém o item ao qual você quer se conectar.
• Permissão para acessar o espaço de trabalho e o item de origem.
• O ID do espaço de trabalho e o ID do item, que você pode encontrar na URL do Fabric ou usando o comando de pesquisa do conector.

Encontre um item do Fabric

Use connector search para listar itens de um tipo específico em um espaço de trabalho. O exemplo a seguir lista armazéns:

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

Substitua <workspace-id> pela ID do espaço de trabalho do Fabric. Para buscar outro item suportado, mude o --type valor. Você também pode adicionar um filtro de nomes:

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

Copie o ID do item do resultado da busca.

Adicionar um conector

Execute o comando connector add no diretório raiz do seu projeto Fabric Apps. O exemplo a seguir adiciona um conector de armazém somente leitura chamado inventory:

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

Use o tipo de conector correspondente e as operações para outros itens do 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

O comando:

• Adiciona o conector à seção de nível connectors superior em rayfin/rayfin.yml.
• Cria os arquivos conectores sob rayfin/connectors/<connector-name>/.
• Exibe um comando npm install com versão correspondente para os pacotes de conector necessários.

Execute o comando de instalação exato exibido pela CLI. Isso mantém os pacotes de conectores alinhados com a versão da sua CLI Rayfin.

A configuração gerada utiliza autenticação delegada. Uma configuração de armazém e modelo semântico se assemelha ao seguinte exemplo:

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

Mantenha o valor do modelo version semântico que a CLI gera.

Configurar um conector de entidade

Conectores Lakehouse, warehouse e banco de dados SQL expõem tabelas de origem selecionadas como entidades tipadas. Use o arquivo gerado metadata.json para definir apenas as tabelas e colunas que seu app precisa.

O exemplo a seguir assume que o warehouse selecionado contém uma dbo.Order tabela com uma chave primária inteira chamada OrderID e uma coluna de texto chamada customerEmail. Substitua esses nomes e tipos ilustrativos por valores dos seus metadados gerados.

Crie a entidade:

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

Depois, registre a entidade no esquema do 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
>;

Mantenha o nome do conector, a propriedade do esquema e o nome da configuração do cliente consistentes.

Configurar o cliente dos conectores

Adicione os esquemas de conectores a ConnectorsRayfinClient. Conectores de modelos semânticos também exigem o ambiente de execução 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(),
  }
);

Use a URL da API e a chave publicável do seu projeto Fabric Apps. Mantenha o fluxo de login já existente no app. Criar o cliente não conecta um usuário.

Consultar dados conectados

Depois que o usuário fizer login, acesse um conector de entidade por meio do nome e da entidade:

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

Selecione as colunas explicitamente e limite o número de linhas retornadas.

Para um modelo semântico, envie uma consulta DAX com 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);
}

Substitua Sales por uma tabela no seu modelo semântico. Verifique o status retornado antes de usar o resultado.

Acesso seguro ao conector

Use esses controles juntos:

• Limite, em rayfin.yml, as operações do conector às ações de que o aplicativo precisa.
• Adicionar @role declarações às entidades conectores para controlar quais usuários logados podem realizar cada operação.
• Adicione políticas de linha ou regras de inclusão e exclusão de campos quando os usuários precisarem de acesso apenas a uma parte de uma entidade.
• Mantenha a autenticação delegada ativada para que as requisições de conexão usem o acesso do usuário logado.

Tipos TypeScript do lado do cliente melhoram a segurança do desenvolvimento, mas não são um limite de autorização. Aplique o acesso na configuração do conector e nas funções da entidade.

Implantar o conector

Implante o aplicativo e a configuração do conector:

npx rayfin up

Teste o aplicativo implantado com um usuário que tenha as permissões esperadas tanto no app Fabric quanto no item conectado.

Conteúdo relacionado

• Crie um aplicativo conectado a um modelo semântico
• Definir modelos de dados
• Definir permissões de dados
• Autenticação para Aplicativos Fabric
• Implantar um aplicativo do Fabric no Fabric
• Referência da CLI do Rayfin