Fabric Uygulamaları için veri modelleri tanımlama

Fabric Apps, veritabanı tabloları ve API'leri oluşturan veri modellerini tanımlamak için TypeScript dekoratörlerini kullanır. Her varlığı ile @entity()dekore edilmiş bir sınıf olarak tanımlarsınız, veri türleri için alan dekoratörleri ekler ve varlıklar arasındaki ilişkileri eşlersiniz.

Yetkilendirme ve erişim denetimi kılavuzu için bkz. Veri izinlerini tanımlama.

Prerequisites

  • npm create @microsoft/rayfin@latest ile oluşturulan veya npx rayfin init ile başlatılan bir Fabric Apps projesi.
  • TypeScript sınıfları ve dekoratörleri hakkında temel bilgiler.

Varlık tanımlama

Varsayılan blankapp şablon, Veri devre dışı bırakılmış bir Universal App çalışma alanı oluşturur. Şablonun veri modelleme yeteneğiyle bunu etkinleştirin:

npm run pack:add -- data-modeling

Bu adım, başlangıç varlığı ve paylaşılan sözleşme ekler. Varlık sınıflarını packages/data/src/ içine yerleştirin, onları packages/data/src/index.ts içinde kaydedin ve istemciye dönük sözleşmeleri packages/shared/src/index.ts içinde koruyun. Veri servisi, services.data.path: packages/data içinde rayfin/rayfin.yml kullanır. Fabric için Data'yı manuel olarak yapılandırdığınızda, dialect: mssql ve enabled: true öğelerini de ayarlayın.

Düz şablonlar ise varlıkları rayfin/data/ içinde tutabilir ve rayfin/data/schema.ts kullanabilir. İkinci bir veri klasörü oluşturmak yerine yapılandırılmış hizmet yollarınızı takip edin. Proje yapısı'na bakın.

Veri modeli oluşturmak için dekoratörü bir TypeScript sınıfına ekleyin @entity() . Ardından gerekli dekoratörleri @microsoft/rayfin-core öğesinden içeri aktarın:

import { entity, uuid, text, date } from '@microsoft/rayfin-core';

@entity()
export class Todo {
  @uuid() id!: string;
  @text({ max: 200 }) title!: string;
  @text({ optional: true, max: 2000 }) description?: string;
  @date() createdAt!: Date;
  @date() updatedAt!: Date;
}

Bu varlık, Todo, id, title, description ve createdAt için sütunlar içeren bir updatedAt tablo oluşturur.

Important

Persist edilen metin alanlarına verilerinize uygun açık bir maksimum uzunluk verin. Microsoft SQL Server'da, max olmadan metin NVARCHAR(MAX) oluşturur ve bu da GraphQL meta veri üretimini engelleyebilir. Örnekler, sahip ve yabancı anahtar dizileri dahil olmak üzere sınırlandırılmış metin kullanır. Veri modeli sorunlarını giderme konusuna bakın.

Birincil anahtarlar

Her varlık birincil anahtarı olarak adlı string bir UUID id alanı kullanır. id açıkça bildirmezseniz Fabric Uygulamalar bunu şemaya otomatik olarak ekler.

  • Oluşturma id işlemleri sırasında bu alan isteğe bağlıdır; bunu atlarsanız sunucu bir UUID oluşturur.
  • İstemci tarafından oluşturulan tanımlayıcıları tercih ediyorsanız oluşturma zamanında kendi UUID'nizi sağlayabilirsiniz.
  • Bileşik birincil anahtarlar ve özel anahtar adları desteklenmez.
@entity()
export class Note {
  @uuid() id!: string;  // UUID primary key, auto-generated when omitted
  @text({ max: 200 }) title!: string;
  @text({ max: 4000 }) content!: string;
}

Desteklenen veri türleri

Alan türlerini tanımlamak için şu dekoratörleri kullanın:

Dekoratör Türü Açıklama
@uuid() string Benzersiz tanımlayıcı alanı.
@text({ max: n }) string Veritabanında saklanan MSSQL sütunları için açık bir maksimum uzunluğa sahip metin alanı.
@int() number Tamsayı alanı.
@decimal() number Ondalık veya sayısal alan.
@boolean() boolean Doğru veya yanlış alanı.
@date() Tarih Tarih ve saat alanı, ISO dizelerinden veya Date nesnelerinden serileştirilir.
@email() string E-posta doğrulamalı metin alanı.
@set() string Numaralandırılmış dize değişmez değerleri kümesi.

Birden çok türü olan örnek

import { entity, uuid, text, int, decimal, boolean, date, set } from '@microsoft/rayfin-core';

@entity()
export class Product {
  @uuid() id!: string;
  @text({ max: 200 }) name!: string;
  @decimal() price!: number;
  @int() stockQuantity!: number;
  @boolean() isAvailable!: boolean;
  @date() createdAt!: Date;
  @set('draft', 'published', 'archived') status!: 'draft' | 'published' | 'archived';
}

Tür değiştiricileri

Doğrulamayı ve kısıtlamaları yapılandırmak için alan dekoratörlerine değiştiriciler ekleyin:

Değiştirici Açıklama
{ optional: true } NULL değerlerine izin ver. Alanlar varsayılan olarak gereklidir.
{ unique: true } Benzersiz bir kısıtlama ekleyin.
{ default: value } Varsayılan değer ifadesini ayarlayın.
{ max: n }, { min: n } Dize uzunluğu kısıtlamaları (en fazla ve en az karakter sayısı).
{ min: n }, { max: n } Sayısal değer kısıtlamaları.

Uyarı

TypeScript isteğe bağlı işaretçisi (? özellik adından sonra) yalnızca statik TypeScript türünü etkiler. Veritabanı sütununu NULL olabilir hale getirmez. Bir alanı null değer alabilir hale getirmek için dekoratöre { optional: true } ekleyin. Çerçevenin gerekli bir alanı başlattığını belirtmek için ! kullanın.

Değiştiriciler içeren örnek

@entity()
export class User {
  @uuid() id!: string;
  @email({ unique: true, max: 254 }) email!: string;
  @text({ min: 3, max: 50 }) username!: string;
  @text({ optional: true, max: 500 }) bio?: string;
  @int({ min: 0, max: 150 }) age!: number;
  @boolean({ default: false }) isVerified!: boolean;
}

İlişkileri tanımlama

Varlıklar arasında gezinti özelliklerini tanımlamak için @one() ve @many() dekoratörlerini kullanın. Fabric Apps, ilişkileri tanımladığınızda yabancı anahtar sütunlarını otomatik olarak oluşturur.

  • Bire-çok – Ana öğede @many(), alt öğede @one() kullanın.
  • Çoktan bire – Alt öğede üst öğeye başvurmak için @one() kullanın.
  • Çoktan çoğa ilişkileri desteklenmez—bunun yerine açık bir birleştirme varlığı kullanın.

Bire-çok ilişkisi içeren örnek

import { entity, uuid, text, date, one, many } from '@microsoft/rayfin-core';

@entity()
export class Notebook {
  @uuid() id!: string;
  @text({ max: 200 }) name!: string;
  @date() createdAt!: Date;
  @many(() => Note) notes?: Note[];
}

@entity()
export class Note {
  @uuid() id!: string;
  @text({ max: 200 }) title!: string;
  @text({ max: 4000 }) content!: string;
  @date() createdAt!: Date;
  @text({ max: 36 }) notebook_id!: string;
  @one(() => Notebook) notebook?: Notebook;
}

@one(() => Notebook) varlığında Note tanımladığınızda, Fabric uygulamaları otomatik olarak bir notebook_id yabancı anahtar sütunu oluşturur. Yabancı anahtar alanını yalnızca uygulama kodunda okumayı veya ayarlamayı planlıyorsanız açıkça bildirin.

Yabancı anahtar adlandırma kuralı

Yabancı anahtar alanı tanımlarken adlandırma kuralını kullanın {property}_id :

@entity()
export class Note {
  @uuid() id!: string;
  @text({ max: 36 }) notebook_id!: string;      // Foreign key field
  @one(() => Notebook) notebook?: Notebook;  // Navigation property
}

Özel yabancı anahtar adları (foreignKey, targetKey seçenekleri) desteklenmiyor.

Referans sistemi varlıkları

Fabric Uygulamaları, yerleşik @one() varlığı gibi sistem varlıklarına işaret eden USER ilişkilerini desteklemez. Giriş yapan kullanıcıya bir satırı ilişkilendirmek için, sınırlı user_id bir metin alanı ekleyin ve onu kimlik doğrulama taleplerinden doldurun (genellikle claims.sub):

@entity()
export class Task {
  @uuid() id!: string;
  @text({ max: 200 }) title!: string;
  @text({ max: 255 }) user_id!: string;  // System user ID from claims.sub
}

Rol ilkelerinizde satırları user_id’e göre filtreleyerek kullanıcı bazında erişimi zorunlu kılın.

Şemada varlıkları kaydetme

Universal App çalışma alanında, çalışma zamanı varlık sınıflarını packages/data/src/index.ts içinde kaydedin:

import { Note } from './Note.js';
import { Notebook } from './Notebook.js';

export const schema = [Note, Notebook];

İlgili kayıt arayüzlerini ve UniversalAppSchema eşlemesini packages/shared/src/index.ts içinde bu varlıklarla hizalı tutun. Ön yüz, @rayfin-app/shared konumundan UniversalAppSchema içe aktarır; dekore edilmiş çalışma zamanı sınıflarını içe aktarmaz. Verileri okuma ve yazma bölümündeki sayısal toplama örneklerini kullanıyorsanız, Product öğesini her iki kayda da ekleyin.

düz şablon alternatifi için, rayfin/data/schema.ts içinde varlık türlerini eşleyin:

import type { Note } from './Note.js';
import type { Notebook } from './Notebook.js';

export type NotesAppSchema = {
  Note: Note;
  Notebook: Notebook;
};

Yeni bir varlık oluşturduğunuzda seçtiğiniz düzen için kayıtları ve şema türlerini güncelleyin.

Şema değişikliklerini uygulayın

Varlıkları tanımladıktan veya değiştirdikten sonra, değişiklikleri veritabanına uygulayın. Tam dağıtım ve doğrulama iş akışı için Uygulama ve şema değişikliklerini doğrula'na bakınız.

  1. Güncelleştirilmiş şemayı Fabric dağıtın:

    npx rayfin up db apply

  2. Şema değişikliği yıkıcı işlemler içeriyorsa (sütunları bırakma, tabloları yeniden adlandırma), CLI sizi uyarır ve devam etmeyi reddeder. Güvenlik denetimini geçersiz kılmak için kullanın --force :

    npx rayfin up db apply --force

Uyarı

kullanmak --force veri kaybına neden olabilir. Devam etmeden önce listelenen işlemleri dikkatle gözden geçirin.

En iyi uygulamalar

  • Yabancı anahtar alanlarını yalnızca kodda okumanız veya ayarlamanız gerektiğinde tanımlayın; Fabric Uygulamalar bunları gezinti dekoratörlerinden otomatik olarak oluşturur.
  • Yayımlanan ESM JavaScript’in doğru şekilde çözümlenmesini sağlamak için entity dosyalarında .js uzantılarını içeren göreli içe aktarmaları kullanın.
  • Yetkilendirme desenleri ve rol tabanlı erişim için bkz. Veri izinlerini tanımlama.

Troubleshooting

Eksik ilişkiler

API'de ilişkiler görünmüyorsa şunları doğrulayın:

  • Gezinti dekoratörü (@one() veya @many()) mevcut.
  • Varlık, yapılandırılmış veri paketinizde ve paylaşılan şemanızda ya da düz bir şablon için rayfin/data/schema.ts kayıtlıdır.

İlgili içerik

  • Son güncelleştirme: