Fabric Uygulamalarını Fabric verilerine bağla

Bağlayıcılar, bir Fabric uygulamasından diğer Fabric öğelerindeki verilere yazılı erişim sağlar. Ayrı bir veri hizmeti yapılandırmadan Fabric’teki veri gölü evi, ambar, SQL veritabanı veya semantik modeli sorgulamak için bir bağlayıcı kullanın.

Desteklenen bağlayıcılar

Uygulamanızın ihtiyaç duyduğu Fabric öğesi ve işlemlerine göre bir bağlayıcı seçin:

Kumaş parçası Bağlayıcı türü Desteklenen işlemler
Lakehouse SQL analiz uç noktası fabric-sqlanalytics read
warehouse fabric-warehouse read, create, update ve delete
Fabric'de SQL veritabanı fabric-sqldatabase read, create, update ve delete
Semantik model fabric-semanticmodel executeQuery

Fabric bağlayıcılarında depo ve SQL veritabanı için, sadece uygulamanızın ihtiyaç duyduğu işlemleri yapılandırın. Göl evi bağlantısı sadece okunabilir.

Prerequisites

  • npm create @microsoft/rayfin@latest ile oluşturulan veya npx rayfin init ile başlatılan bir Fabric Apps projesi.
  • Bağlanmak istediğiniz öğeyi içeren bir Fabric çalışma alanı.
  • İş alanı ve kaynak öğesine erişim izni.
  • Fabric URL’sinde veya bağlayıcı arama komutunu kullanarak bulabileceğiniz çalışma alanı kimliği ve öğe kimliği.

Bir Fabric ürünü bul

Belirli bir türdeki öğeleri bir çalışma alanında listelemek için kullanın connector search . Aşağıdaki örnek depoları listeliyor:

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

<workspace-id> ifadesini Fabric çalışma alanı kimliğiniz ile değiştirin. Desteklenen başka bir öğe aramak için değeri --type değiştirin. Ayrıca bir isim filtresi de ekleyebilirsiniz:

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

Arama sonucundan ürün kimliğini kopyalayın.

Bağlayıcı ekleme

Fabric Apps projenizin kökünden başlayınconnector add. Aşağıdaki örnek, yalnızca okunabilir bir depo bağlayıcısı ekliyor:inventory

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

Diğer Fabric öğeleri için ilgili bağlantı tipi ve işlemlerini kullanın:

# 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

Komut:

  • Bağlantıyı rayfin/rayfin.yml içindeki en üst düzey connectors bölümüne ekler.
  • Bağlantı dosyalarını . rayfin/connectors/<connector-name>/altında oluşturur.
  • Gerekli bağlayıcı paketleri için sürümü eşleşen bir npm install komutu yazdırır.

CLI tarafından basılan tam kurulum komutunu çalıştırın. Bu, konnektör paketlerini Rayfin CLI versiyonunuzla hizalanmış tutar.

Uyarı

Şema keşfi en iyi çabadır. Keşif tamamlanmasa bile bağlantı eklenebilir. Eğer CLI bir keşif uyarısı gösterirse, oluşturulan metadata.json dosyadan varlıkları tanımlamadan önce bunu çözebilirsiniz.

SQL bağlayıcı türleri (fabric-sqlanalytics, fabric-warehouse ve fabric-sqldatabase) CLI 1.36.2'de varsayılan olarak uygulama doğrulamasını kullanır. Şu anda uygulama öğesinin sahibi olan uygulama kimliğiyle kaynağa erişirler. Her giriş yapan çağıranın kaynak izinlerini kullanmak için açıkça delege edilmiş kimlik doğrulamayı seçebilirsiniz. Semantik modeller yalnızca delege edilmiş kimlik doğrulamayı destekler.

Varsayılan depo ve anlamsal model konfigürasyonu şöyle görünür:

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

CLI'nin ürettiği anlamsal model version değerini koruyun.

Kaynak kimliğini seçin

Mode Kaynak izinleri Ne zaman kullanılır?
application Uygulama kimliğine kaynak öğeye ve gerekli SQL izinlerine erişim ver. Uygulama kullanıcılarının hâlâ uygulama erişimine ve varlık izinlerine ihtiyacı var. Paylaşılan kaynak verilere uygulama kontrollü erişimi açan SQL bağlayıcıları.
delegated Her arayan, kaynak öğeye erişim ve istenen işlem için izne sahip olmalıdır. Semantik model sorguları, Build dahil olmak üzere çağıranın geçerli model izinlerini gerektirir. Kullanıcı başına kaynak erişim yetkisi veya herhangi bir anlamsal model bağlayıcısı.

CLI 1.36.2'de delege edilmiş SQL erişimi için, dağıtmadan önce rayfin/rayfin.yml içinde o konnektörde auth.type: delegated ayarlayın. CLI sürümleri, --auth öğesinin connector add --help öğesini gösterdiği durumlarda, bunu oluşturma sırasında seçebilir:

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

Bu --auth bayrak CLI 1.36.2'de mevcut değil; o sürümde YAML ayarını kullanın. Bayrak desteklendiğinde, yalnızca konnektör tipi o modu destekliyorsa application veya delegated kabul eder. Bir semantik model için uygulama kimlik doğrulamasını yapılandırmayın.

Modu değiştirmek kaynak izinleri vermez. Geliştirici giriş ve şema keşfi, geliştiricinin erişimini kullanır ve dağıtılan çalışma zamanı kimliğinin kaynağa erişebileceğini kanıtlamaz. Mevcut beyanlar otomatik olarak yeni varsayılana taşınmaz; auth.type ifadesini açıkça koruyun. Bir konnektör yeniden eklendikten sonra, dağıtımdan önce oluşturulan yapılandırmayı gözden geçirin.

Varlık bağlayıcısını yapılandırın

Lakehouse, veri ambarı ve SQL veritabanı bağlayıcıları, seçilen kaynak tablolarını türlendirilmiş varlıklar olarak sunar. Oluşturulan metadata.json dosyayı kullanarak sadece uygulamanızın ihtiyaç duyduğu tabloları ve sütunları tanımlayın.

Aşağıdaki örnek, seçilen deponun dbo.Order adlı, OrderID adlı tamsayı birincil anahtara ve customerEmail adlı bir metin sütununa sahip bir tablo içerdiğini varsayar. Bu açıklayıcı isimleri ve türleri oluşturulan metaverideki değerlerle değiştirin.

Important

Bir sütun adından birincil anahtar çıkarmayın. Kaynak tabloda bir anahtar yoksa, primaryKey öğesini atlayın. Anahtarsız varlıklar, bir satırı anahtarına göre hedefleyen işlemleri desteklemez.

Varlığı oluşturun:

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

Sonra varlığı bağlantı şemasına kaydedin:

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

Bağlayıcı adı, şema özelliği ve istemci yapılandırma adını tutarlı tutun.

Konnektör istemcisini yapılandırma

Bağlantı şemalarını ekleyin.ConnectorsRayfinClient Anlamsal model bağlayıcıları ayrıca fabricSemanticModel() çalışma zamanını gerektirir:

// 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(),
  }
);

Fabric Apps projenizdeki API URL'sini ve yayınlanabilir anahtarı kullanın. Uygulamanın mevcut giriş akışını koruyun. İstemciyi oluşturmak, kullanıcının oturum açmasını sağlamaz.

Bağlantılı veri sorgulama

Kullanıcı giriş yaptıktan sonra, bir varlık bağlayıcısına adı ve varlığı üzerinden erişin:

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

Sütunları açıkça seçin ve geri dönen satır sayısını sınırlayın.

Bir anlamsal model için, aşağıdaki dax sorgusu executeQuerygönderin:

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

Yerine Sales semantik modelinizde bir tablo ekleyin. Sonucu kullanmadan önce döndürülen durumu kontrol edin.

Güvenli bağlantı erişimi

Bu kontrolleri birlikte kullanın:

  • Bağlayıcının işlemlerini rayfin.yml uygulamanın ihtiyaç duyduğu eylemlerle sınırlayın.
  • Hangi giriş yapan kullanıcıların her işlemi gerçekleştirebileceğini kontrol etmek için bağlayıcı varlıklara bildirmeler ekleyin @role .
  • Kullanıcıların bir varlığın yalnızca bir bölümüne erişmesi gerektiğinde satır ilkeleri veya alan dahil etme ve hariç tutma kuralları ekleyin.
  • Kaynak kimliğini bilinçli olarak seçin. Uygulama kimlik doğrulamasında, her arayan için kaynak izinlerinin kontrol edildiğini varsaymak yerine uygulama ve varlık izinleri üzerinden kullanıcı başına erişimi zorunlu kılın. Devredilmiş kimlik doğrulama ile, her arayanın kaynağa erişim yetkisini de doğrulayın.

İstemci tarafı TypeScript tipleri geliştirme güvenliğini artırır, ancak yetkilendirme sınırı değildirler. Bağlantı yapılandırmasında ve varlık rollerinde erişimi zorunlu kılın.

Bağlayıcıyı dağıtın

Uygulama ve konnektör yapılandırmasını dağıtın:

npx rayfin up

Dağıtılan uygulamayı beklenen uygulama kullanıcıları ve çalışma zamanı kaynak kimliğiyle test edin. Uygulama kimlik doğrulaması için, uygulama kimliğinin kaynak izinlerini doğrulayın; Devredilen kimlik doğrulama için ise her arayanın kaynak izinlerini doğrulayın.

İlgili içerik

  • Son güncelleştirme: