Anlam modeline bağlı bir uygulama oluşturma

Veri uygulaması şablonunu Fabric anlamsal model bağlayıcısıyla birlikte kullanarak analitik bir Fabric uygulaması oluşturun. Şablon, görselleştirme, biçimlendirme, veri ızgarası ve tarayıcı doğrulama desenleri sağlar. Bağlayıcı, Fabric Apps istemcisi aracılığıyla bir semantik modele türlendirilmiş, delege edilmiş erişim sağlar.

Şablonla oluşturulan uygulamalar şunlardır:

Fabric doğrulaması.
Daha yüksek kaliteli DAX (Veri Analizi İfadeleri) oluşturma yönergeleri.
Analitik uygulamalar için tasarlanmış kurumsal hazır görsel bileşenler.
Veri ızgarası, tema, biçimlendirme ve tarayıcı doğrulama kalıpları.

Uyarı

Şu anda, Rayfin CLI, veri uygulaması şablonunu kullanarak uygulama oluşturmanın desteklenen yoludur.

Veri uygulaması şablonunu neden kullanmalısınız?

Bu yerleşik yetenekler olmadan, bir kodlama ajanı her oturumda kimlik doğrulama, DAX üretimi ve görselleştirme tasarımını sıfırdan çözmek zorundadır. Bu da şu noktalara yol açabilir:

Daha fazla başarısızlık ve kırık ya da boş görseller.
Tutarsız grafik davranışı.
Geliştirme ve çalışma zamanı sırasında gereksiz DAX sorguları.

Şablon, güvenilirliği artıran, raporlama en iyi uygulamalarıyla uyumlu daha uyumlu görseller üreten ve sorgu yükünü azaltan yeniden kullanılabilir kalıplar sunar. Konnektör, anlamsal model yapılandırmasını ve çalışma zamanı erişimini standartlaştırır.

Prerequisites

Node.js 20 veya üzeri.
Fabric’e erişim.
Katkıda Bulunan, Üye veya Yönetici izinlerine sahip olduğunuz bir Fabric çalışma alanı.
Kiracınızda etkin olan Fabric Uygulamaları iş yükü. İlk Fabric uygulamanızı oluştur sayfasına bakınız.
Semantik Model Sorgu Yürütme REST API kiracı ayarı etkinleştirildi.
Fabric veya Power BI kapasitesinde barındırılan bir semantik model üzerindeki Oluşturma ve Okuma izinleri.
Çalışma alanı kimliği ve anlamsal model için öğe kimliği.

Uygulamayı oluşturma

Veri uygulaması şablonundan bir proje oluşturun:

npm create @microsoft/rayfin@latest -- "<app-name>" --template dataapp --workspace <workspace-name>

<app-name> ve <workspace-name> yerine uygulamanızın ve Fabric çalışma alanınızın adlarını yazın. Sonra yeni proje klasörünü açın:

cd <app-name>

Semantik model konnektörünü ekleyin

Anlamsal model öğe kimliğini bilmiyorsanız, çalışma alanında anlamsal modelleri listeleyin:

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

Anlamsal modeli bir bağlayıcı olarak ekleyin:

npx rayfin connector add --type fabric-semanticmodel --workspace-id <workspace-id> --item-id <semantic-model-item-id> --name salesModel --operations executeQuery

Komut:

salesModel bağlayıcısını rayfin/rayfin.yml öğesine ekler.
Şemasını . rayfin/connectors/salesModel/altında oluşturur.
Konnektör 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.

Oluşturulan yapılandırma aşağıdaki örneğe benzer:

connectors:
  - name: salesModel
    type: fabric-semanticmodel
    config:
      workspaceId: "<workspace-id>"
      itemId: "<semantic-model-item-id>"
    auth:
      type: delegated
    version: "1"
    operations:
      - name: executeQuery

Üretilen version değeri koruyun.

Şablonu anlamsal modele bağlayın

Şablon, konnektörle tekrar kullanabileceğiniz analitik bileşenler ve ajan rehberliği içerir. Veri erişim katmanını bir ConnectorsRayfinClient oluşturacak şekilde yapılandırın ve anlamsal model çalışma zamanını kaydedin:

Important

Semantik model sorguları için connector istemcisini kullanın. Eğer iskele başka bir anlamsal model istemcisi içeriyorsa, iki veri erişim yolunu sürdürmek yerine ona yapılan çağrıları değiştirin.

import { ConnectorsRayfinClient } from '@microsoft/rayfin-client';
import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
import {
  connectorConfig,
  type SalesModelSchema,
} from '../../rayfin/connectors/salesModel/schema.js';

type AppConnectorsSchema = {
  salesModel: SalesModelSchema;
};

export const client = new ConnectorsRayfinClient<
  Record<string, never>,
  Record<string, never>,
  AppConnectorsSchema
>(
  {
    baseUrl: '<app-api-url>',
    publishableKey: '<publishable-key>',
    authStorage: true,
    connectors: {
      salesModel: connectorConfig,
    },
  },
  {
    salesModel: fabricSemanticModel(),
  }
);

Fabric Apps projenizdeki API URL'sini ve yayınlanabilir anahtarı kullanın. Şablonun mevcut Fabric giriş akışını koruyun.

DAX'ı konnektör üzerinden gö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. Sütunları ve satırları görsel olarak iletmeden önce geri dönme durumunu kontrol edin.

Daha fazla konnektör yapılandırması ve güvenlik rehberliği için Connect Fabric Apps to Fabric data'ya bakınız.

Uygulamayı bir kodlama ajanı ile oluşturun

İskele, kodlama ajanları için talimatlar ve beceriler içerir. Tercih ettiğiniz ajanda projeyi açın ve uygulama hedef kitlesini, soruları, etkileşimleri ve görselleştirmelerini tarif edin.

Örneğin şunları yapabilirsiniz:

Projeyi Visual Studio Code'da açın ve ardından GitHub Copilot Chat panelini açın.
Projede bir terminal açın ve sonra çalıştırın copilot.

Bu promptu başlangıç noktası olarak kullanın:

Build an analytical Fabric app that uses the existing salesModel connector.

Before editing:
1. Read the repository instructions and skills.
2. Inspect rayfin/connectors/salesModel/schema.ts and the template's data-access,
   visualization, data grid, formatting, and validation patterns.
3. Query the semantic model metadata before writing DAX. Don't guess table,
   measure, or column names.

Requirements:
- Use ConnectorsRayfinClient and fabricSemanticModel() for semantic model access.
- Call client.connectors.salesModel.executeQuery() for DAX queries.
- Keep the existing Fabric sign-in flow. Don't add credentials, access tokens,
  another authentication flow, or direct calls to the Execute Queries REST API.
- Reuse query results where practical, and bound large result sets.
- Apply semantic model format strings consistently to cards, charts, tooltips,
  and data grids.
- Include loading, empty, and error states.
- Use the template's browser-validation workflow at desktop and mobile sizes.

Give me a short implementation plan, make the changes, run the existing build,
and report the results.

Şablon yeteneklerini kullanın

Veri uygulaması şablonu, analitik uygulamalar için yeniden kullanılabilir desenler içerir.

Fabric Apps standart web uygulamalarıdır, bu yüzden bu kalıpların dışındaki özellikleri uygulayabilirsiniz. Şablonda yer almayan özellikler daha fazla özel mühendislik ve doğrulama gerektirebilir.

Visuals

Şablon, çapraz vurgulama ve önceden yapılandırmalı ilkeller içerir:

Diki, yatay, gruplanmış ve üst üste yığılmış düzenleri içeren çubuk grafikler.
İsteğe bağlı işaretçili çizgi grafikleri.
Alan haritaları.
Dağılım grafikleri.
Turta ve donut haritaları.
Isı haritaları.
Balon grafikleri.
Şelale haritaları.
KPI vurguları için tek değer içeren kartlar.
Katmanlı ve bileşik görseller, veri etiketli çubuklar ve çift eksenli çizgi grafikleri gibi.

Bağlantılı anlamsal modelde var olan alanları ve ölçümleri kullanın. Başarısız bir konnektör sorgusunu mock veri ile değiştirmeyin.

Kodlama ajanınızdan başka görseller üretmesini isteebilirsiniz. Şablon ilkel olmayan görseller daha fazla yineleme ve doğrulama gerektirebilir.

Veri ızgarası özellikleri

Şablon, şu önceden yapılandırılmış yeteneklere sahip bir veri ızgarasını içerir:

Anlamsal model metaverisinden türetilen sütun başlıkları.
Sayı ve tarih biçimlendirilmesi, format dizileri aracılığıyla sütun başına uygulanır.
Sıralama.
Kaydırılabilir sıralar ve taşma işlemesi.
Açık ve koyu tema desteği.
Özel hücre renderörleri için:
- Sayısal değerler için veri çubukları.
- Boolean göstergeler.
- Tıklanabilir URL'ler.
- Işık kutusu üst katmanlı görüntü hücreleri.
- Bir sütunda ad ve rol gibi birden fazla alan içeren hücreler.

Başka veri ızgarası yetenekleri de ekleyebilirsiniz, ancak bunlar daha fazla özel mühendislik gerektirebilir.

Tema oluşturma

Kodlama ajanınıza renk paleti, köşe stili veya yazı tipi gibi marka veya stil gereksinimlerini belirtin. Şablon, paylaşılan stilleri tek bir merkezi konumda tutar, böylece akış kartlara, düğmelere, grafiklere, veri ızgaralarına ve ipuçlarına değişir.

Merkezi tasarım, uyumsuz renkleri, tutarsız yazı tiplerini ve her bileşen ayrı stilize edildiğinde ortaya çıkabilecek düzen farklılıklarını önler.

Dizeleri biçimlendirme

Her sonuç sütunu için biçimlendirmeyi bir kez tanımlayın. Şablon, grafik eksenleri, araç ipuçları, veri etiketleri, kartlar ve veri ızgarası hücreleri arasında anlamsal model format dizelerini yeniden kullanabilir.

Örneğin, tek bir biçim tanımı, bu değerler nerede görünürse görünsün, 1500.5 değerinin $1,500.50 olarak ve 0.25 değerinin 25% olarak görüntülenmesini sağlar.

Tarayıcı doğrulaması

Uygulamayı yayınlamadan önce, dahil edilen Playwright tarayıcı doğrulama iş akışını kullanarak gerçek bir tarayıcıda açın ve şu noktaları kontrol edin:

Görseller doğru şekilde görüntüleniyor.
Grafikler kesilmez veya sıkıştırılmaz.
Metin okunabilir.
Veri ızgaraları taşmayı işler.
Yükleme, boş ve hata durumları kullanışlıdır.
Filtreler, çapraz vurgulama ve veri biçimlendirmesi beklendiği gibi çalışıyor.
Tarayıcı konsolunda beklenmedik hata yok.

Bu iş akışı, kullanıcılar görmeden önce yerleşim ve işleme sorunlarını yakalar. Tarayıcı doğrulaması ön uç davranışını doğrular. Dağıtılan konnektörü, hem Fabric uygulamasına hem de semantik modele erişimi olan bir kullanıcıyla ayrı ayrı test edin.

Uygulamayı dağıtın ve doğrulayın

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

npx rayfin up

Fabric portalından dağıtılan uygulamayı açın. Giriş yapın, her kullanıcı etkileşimini çalıştırın ve önemli sonuçları anlamsal modelle karşılaştırın.

Bir sorgu başarısız olursa:

rayfin.yml içindeki çalışma alanı ve anlamsal model öğe kimliklerini doğrulayın.
Anlamsal Model Sorgu Yürütme REST API kiracı ayarının etkin olduğundan emin olun.
Kullanıcının semantik modelde Build ve Read izinlerine sahip olduğunu doğrulayın.
DAX'ın mevcut tablolara, sütunlara ve ölçülere referans verdiğinden emin olun.
Konnektör sonucunun hata kategorisini ve mesajını kontrol et.
İstemci tarafı hataları için tarayıcı konsolunu kontrol edin.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Son güncelleştirme: 2026-09-29