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

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() title!: string;
  @text({ optional: true }) description?: string;
  @date() createdAt!: Date;
  @date() updatedAt!: Date;
}

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

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() title!: string;
  @text() 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()	string	İsteğe bağlı uzunluk kısıtlamaları olan 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() 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 }) 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() name!: string;
  @date() createdAt!: Date;
  @many(() => Note) notes?: Note[];
}

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

Note varlığında @one(() => Notebook) 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() 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. Bir satırı oturum açmış kullanıcıyla ilişkilendirmek için, düz user_id türde @text() bir alan ekleyin ve bu alanı kimlik doğrulama taleplerinden doldurun (genellikle claims.sub):

@entity()
export class Task {
  @uuid() id!: string;
  @text() title!: string;
  @text() 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

İstemcinin GraphQL proxy'leri oluşturabilmesi için rayfin/data/schema.ts tüm varlık sınıflarını içine ekleyin:

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 bu türü güncelleştirin.

Şema değişikliklerini uygulayın

Varlıkları tanımladıktan veya değiştirdikten sonra değişiklikleri veritabanına uygulayın:

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, rayfin/data/schema.ts içinde kayıtlıdır.

İlgili içerik

• GraphQL ile verileri sorgulama
• Veri izinlerini tanımlama
• Fabric'e dağıtın