Ligue aplicações Fabric a dados Fabric

Os conectores fornecem acesso digitado de uma aplicação Fabric a dados noutros itens Fabric. Utilize um conector para consultar um lakehouse, armazém de dados, base de dados SQL no Fabric ou um modelo semântico, sem necessidade de configurar um serviço de dados separado.

Conectores suportados

Escolha um conector com base no item Fabric e nas operações que a sua aplicação necessita:

Item de tecido Tipo de conector Operações suportadas
Ponto de Extremidade de Análise SQL do Lakehouse fabric-sqlanalytics read
warehouse fabric-warehouse read, create, updatee delete
Banco de dados SQL no Fabric fabric-sqldatabase read, create, updatee delete
Modelo semântico fabric-semanticmodel executeQuery

Para armazém e base de dados SQL nos conectores Fabric, configure apenas as operações que a sua aplicação necessita. O conector da casa do lago é só de 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 do Fabric que contém o item ao qual pretende ligar-se.
  • Permissão para aceder ao espaço de trabalho e ao item de origem.
  • O ID do espaço de trabalho e o ID do item, que podes encontrar no URL do Fabric ou usando o comando de pesquisa do conector.

Encontrar um item do Fabric

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

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

Substitua <workspace-id> pelo ID do espaço de trabalho do Fabric. Para procurar outro item suportado, altere o --type valor. 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 de pesquisa.

Adicionar um conector

Executa connector add a partir da raiz do teu projeto Fabric Apps. O exemplo seguinte adiciona um conector de armazém de apenas leitura chamado inventory:

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

Utilize o tipo de conector e as operações correspondentes 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 à secção de nível superior connectors em rayfin/rayfin.yml.
  • Cria os ficheiros do conector em rayfin/connectors/<connector-name>/.
  • Apresenta um comando npm install correspondente à versão dos pacotes de conetores necessários.

Executa exatamente o comando de instalação impresso pelo CLI. Isto mantém os pacotes de conectores alinhados com a versão do CLI do Rayfin.

Note

A descoberta de esquemas é o melhor esforço. O conector pode ser adicionado mesmo que a descoberta não seja concluída. Se a CLI mostrar um aviso de descoberta, resolva-o antes de definir entidades a partir do ficheiro gerado metadata.json .

A configuração gerada utiliza autenticação delegada. Uma configuração de armazém e modelo semântico assemelha-se 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

Mantém o valor do modelo version semântico que a CLI gera.

Configurar um conector de entidade

Os conectores do Lakehouse, do armazém de dados e da base de dados SQL expõem as tabelas de origem selecionadas como entidades com tipos definidos. Use o ficheiro gerado metadata.json para definir apenas as tabelas e colunas que a sua aplicação precisa.

O exemplo seguinte 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 estes nomes e tipos ilustrativos por valores dos seus metadados gerados.

Importante

Não infiras uma chave primária a partir do nome de uma coluna. Se uma tabela de origem não tiver uma chave, omita primaryKey. Entidades sem chave não suportam operações que acedem a uma linha pela chave.

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, regista 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 consistentes o nome do conector, a propriedade do esquema e o nome da configuração de cliente.

Configurar o cliente dos conectores

Adicione os esquemas do conector a ConnectorsRayfinClient. Os conectores de modelos semânticos também requerem o fabricSemanticModel() ambiente de execução:

// 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 a URL da API e a chave publicável do teu projeto Fabric Apps. Mantém o fluxo de login já existente na aplicação. Criar o cliente não autentica um utilizador.

Consultar dados ligados

Depois de o utilizador iniciar sessão, aceda a um conector de entidade através do respetivo 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 devolvidas.

Para um modelo semântico, submeta 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);
}

Substitui Sales por uma tabela no teu modelo semântico. Verifique o estado devolvido antes de usar o resultado.

Acesso seguro por conector

Use estes controlos em conjunto:

  • Limite as operações do conector em rayfin.yml às ações de que a aplicação precisa.
  • Adicionar declarações @role às entidades de conector para controlar que utilizadores com sessão iniciada podem realizar cada operação.
  • Adicione políticas de linha ou regras de inclusão e exclusão de campos quando os utilizadores necessitam de acesso apenas a uma parte de uma entidade.
  • Mantenha a autenticação delegada ativada para que os pedidos de ligação usem o acesso do utilizador iniciado.

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

Implantar o conector

Implemente a aplicação e a configuração do conector:

npx rayfin up

Teste a aplicação implementada com um utilizador que tenha as permissões esperadas tanto na aplicação Fabric como no item ligado.

Conteúdo relacionado

  • Última atualização a