Fabric Apps では、TypeScript デコレーターを使用して、データベース テーブルと API を生成するデータ モデルを定義します。 各エンティティは、 @entity()で修飾されたクラスとして定義し、データ型のフィールド デコレーターを追加し、エンティティ間のリレーションシップをマップします。
承認とアクセス制御のガイダンスについては、「 データのアクセス許可の定義」を参照してください。
前提条件
-
npm create @microsoft/rayfin@latestで作成されるか、npx rayfin initで初期化されたFabric Apps プロジェクト。 - TypeScript クラスとデコレーターの基本的な理解。
エンティティを定義する
デフォルトの blankapp テンプレートは、データを無効にした Universal App ワークスペースを作成します。 テンプレートのデータモデリング機能で有効にします:
npm run pack:add -- data-modeling
このステップでは、スターターエンティティと共有コントラクトが追加されます。 エンティティクラスを packages/data/src/に入れ、 packages/data/src/index.tsに登録し、クライアント向け契約は packages/shared/src/index.tsで維持しましょう。 データサービスはservices.data.path: packages/dataでrayfin/rayfin.ymlを使用しています。 FabricのためにDataを手動設定する際は、enabled: trueとdialect: mssqlも設定してください。
フラットテンプレートは代わりにエンティティを rayfin/data/ に保持でき、rayfin/data/schema.ts を使用できます。 2つ目のデータフォルダを作るのではなく、設定済みのサービスパスに従ってください。
プロジェクト構造を参照してください。
データ モデルを作成するには、typeScript クラスに @entity() デコレーターを追加します。 次に、必要なデコレーターを @microsoft/rayfin-coreからインポートします。
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;
}
このエンティティは、Todo、id、title、description、およびcreatedAtの列を含むupdatedAt テーブルを生成します。
Important
永続的なテキストフィールドには、データに適した明確な最大長さを設定しましょう。 Microsoft SQL Serverでは、maxのないテキストがNVARCHAR(MAX)を生成し、GraphQLのメタデータ生成を妨げる可能性があります。 例では、所有者キーや外部キー文字列を含む bounded text が使われています。 詳細は「データモデルの問題のトラブルシューティング」を参照してください。
主キー
すべてのエンティティは、主キーとして string という UUID id フィールドを使用します。
id を明示的に宣言しない場合は、Fabric Apps によってスキーマに自動的に追加されます。
-
idフィールドは、作成操作中は省略可能です。このフィールドを省略すると、サーバーによって UUID が生成されます。 - クライアントによって生成される識別子を使用する場合は、作成時に独自の UUID を指定できます。
- 複合主キーとカスタム キー名はサポートされていません。
@entity()
export class Note {
@uuid() id!: string; // UUID primary key, auto-generated when omitted
@text({ max: 200 }) title!: string;
@text({ max: 4000 }) content!: string;
}
サポートされているデータの種類
フィールド型を定義するには、次のデコレーターを使用します。
| デコレーター | タイプ | 説明 |
|---|---|---|
@uuid() |
文字列 | 一意の識別子フィールド |
@text({ max: n }) |
文字列 | 永続化されたMSSQL列の明示的な最大長さを持つテキストフィールド。 |
@int() |
数値 | 整数フィールド。 |
@decimal() |
数値 | 10進数フィールドまたは数値フィールド。 |
@boolean() |
boolean | True または false フィールド。 |
@date() |
Date | 日付と時刻フィールド。ISO 文字列または Date オブジェクトからシリアル化されます。 |
@email() |
文字列 | 電子メールの検証を含むテキスト フィールド。 |
@set() |
文字列 | 文字列リテラルの列挙されたセット。 |
複数の型を含む例
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';
}
型修飾子
フィールド デコレーターに修飾子を追加して、検証と制約を構成します。
| 修飾子 | 説明 |
|---|---|
{ optional: true } |
NULL 値を許可します。 フィールドは既定で必須です。 |
{ unique: true } |
一意制約を追加します。 |
{ default: value } |
既定値の式を設定します。 |
{ max: n }、{ min: n } |
文字列の長さの制約 (最大文字数と最小文字数)。 |
{ min: n }、{ max: n } |
数値制約。 |
Note
TypeScript の省略可能なマーカー (プロパティ名の後に? ) は、静的な TypeScript 型にのみ影響します。 データベース列を null 値にすることはできません。 フィールドを null 許容にするには、デコレーターに { optional: true } を追加します。
!を使用して、必要なフィールドがフレームワークによって初期化されていることをアサートします。
修飾子を使用した例
@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;
}
リレーションシップを定義する
@one()および@many()デコレーターを使用して、エンティティ間のナビゲーション プロパティを定義します。 Fabric Apps では、リレーションシップを定義すると外部キー列が自動生成されます。
-
一対多 – 親に
@many()を使用し、子に@one()します。 -
多対一 – 子側で
@one()を使用して親を参照します。 - 多対多リレーションシップはサポートされていません。代わりに明示的な結合エンティティを使用してください。
一対多リレーションシップの例
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) エンティティで Note を定義すると、Fabric Apps によって外部キー列notebook_id が自動的に作成されます。 外部キー フィールドは、アプリケーション コードで読み取りまたは設定する場合にのみ明示的に宣言します。
外部キーの名前付け規則
外部キー フィールドを定義する場合は、 {property}_id 名前付け規則を使用します。
@entity()
export class Note {
@uuid() id!: string;
@text({ max: 36 }) notebook_id!: string; // Foreign key field
@one(() => Notebook) notebook?: Notebook; // Navigation property
}
カスタム外部キー名 (foreignKey、 targetKey オプション) はサポートされていません。
参照システム エンティティ
Fabric Apps では、組み込みの @one() エンティティなどのシステム エンティティを指す USER リレーションシップはサポートされていません。 サインインしたユーザーと行を関連付けるには、バインドされた user_id テキスト フィールドを追加し、認証クレーム (通常は 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
}
ロール ポリシーの user_id で行をフィルター処理して、ユーザーごとのアクセスを強制します。
スキーマにエンティティを登録する
Universal App workspace では、ランタイムエンティティクラスを packages/data/src/index.ts に登録します:
import { Note } from './Note.js';
import { Notebook } from './Notebook.js';
export const schema = [Note, Notebook];
対応するレコードインターフェースと UniversalAppSchema マップは packages/shared/src/index.ts それらのエンティティと整合させてください。 フロントエンドはUniversalAppSchemaから@rayfin-app/sharedをインポートしますが、装飾されたランタイムクラスはインポートしません。
Productの数値集計の例を使用する場合は、両方の登録項目に追加します。
フラットテンプレートの代替として、rayfin/data/schema.tsでエンティティタイプをマップします:
import type { Note } from './Note.js';
import type { Notebook } from './Notebook.js';
export type NotesAppSchema = {
Note: Note;
Notebook: Notebook;
};
新しいエンティティを作成するたびに、選択したレイアウトの登録とスキーマタイプを更新してください。
スキーマの変更を適用する
エンティティを定義または修正した後、その変更をデータベースに適用します。 完全な展開および検証ワークフローについては、「 スキーマの変更を適用し検証」をご覧ください。
更新されたスキーマをFabricにデプロイします。
npx rayfin up db applyスキーマの変更に破壊的操作 (列の削除、テーブルの名前変更) が含まれている場合、CLI によって警告が表示され、続行は拒否されます。
--forceを使用して、安全性チェックをオーバーライドします。npx rayfin up db apply --force
Note
--forceを使用すると、データが失われる可能性があります。 続行する前に、一覧表示されている操作を注意深く確認してください。
ベスト プラクティス
- 外部キー フィールドは、コードで読み取りまたは設定する必要がある場合にのみ定義します。Fabric Apps では、ナビゲーション デコレーターから自動的に生成されます。
- 生成された ESM JavaScript が正しく解決されるように、エンティティ ファイル内の
.js拡張機能で相対インポートを使用します。 - 承認パターンとロールベースのアクセスについては、「データアクセス 許可の定義」を参照してください。
Troubleshooting
リレーションシップが見つからない
API にリレーションシップが表示されない場合は、次のことを確認します。
- ナビゲーション デコレーター (
@one()または@many()) が存在します。 - エンティティは設定されたデータパッケージと共有スキーマに登録されているか、フラットテンプレートの場合は
rayfin/data/schema.tsに登録されています。