Fabric Apps には、生のクエリを記述せずに作成、読み取り、更新、および削除の操作を実行できる、タイプ セーフな GraphQL クライアントが用意されています。 クライアントは、メソッド呼び出しから GraphQL を自動的に生成し、データ モデル定義に基づいて型指定されたエンティティを返します。
前提条件
- データ モデルが定義された Fabric Apps プロジェクト。 データ モデルの定義を参照してください。
- ローカルで実行されているか、Fabricにデプロイされているバックエンド サービス。
クライアントを初期化する
バックエンド URL、発行可能なキー、スキーマの種類を使用して RayfinClient をインスタンス化します。
import { RayfinClient } from '@microsoft/rayfin-client';
import type { UniversalAppSchema } from '@rayfin-app/shared';
const client = new RayfinClient<UniversalAppSchema>({
baseUrl: import.meta.env.VITE_RAYFIN_API_URL,
publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});
ジェネリック型引数を使用すると、TypeScript はすべてのデータ操作にオートコンプリートと型チェックを提供できます。
これらの例は、データを有効にし、packages/data/src/index.ts と Note を Universal App の Notebook および共有スキーマ契約に登録したことを前提としています。 フラットテンプレートなら、 rayfin/data/schema.ts からスキーマタイプをインポートしてください。
データ モデルの定義を参照してください。
データの読み取り
client.data.<EntityName>を介してエンティティ コレクションにアクセスします。 fluent API には、クエリ、フィルター処理、並べ替え、改ページ処理のメソッドが用意されています。
レコードの1ページを取得
execute() デフォルトで100件のレコードを持つ1ページのみを返します。 カーソルのメタデータを返したり、その後のページを取得したりしません。 1ページを超える可能性があるリストには フォワードページング を使いましょう。
const notes = await client.data.Note.select([
'id',
'title',
'content',
'createdAt',
'isPinned',
]).execute();
主キーを使用して単一のレコードを取得する
const note = await client.data.Note.findById('00000000-0000-0000-0000-000000000000');
findById() 記録が存在しない場合は null 返します。 リリースされた実装では主キーのみが選択されているため、他のエンティティフィールドが入力されているとは限りません。 その値が必要な場合に、フィールドを明示的に選択してください:
const notes = await client.data.Note.select(['id', 'title', 'content'])
.where({ id: { eq: '00000000-0000-0000-0000-000000000000' } })
.first(1)
.execute();
const note = notes[0] ?? null;
レコードのフィルター処理
where()メソッドを使用して結果をフィルター処理します。
const pinnedNotes = await client.data.Note.select([
'id',
'title',
'isPinned',
])
.where({ isPinned: { eq: true } })
.execute();
フィルター演算子
| Operator | 説明 | 例 |
|---|---|---|
eq |
等しい | { status: { eq: 'active' } } |
neq |
等しくない | { status: { neq: 'archived' } } |
gt |
より大きい | { age: { gt: 18 } } |
gte |
以上 | { age: { gte: 21 } } |
lt |
未満 | { price: { lt: 100 } } |
lte |
より小さいか等しい | { price: { lte: 50 } } |
contains |
部分文字列を含む | { title: { contains: 'draft' } } |
結果を並べ替える
orderBy()を使用してクエリ結果を並べ替えます。
const notes = await client.data.Note.select([
'id',
'title',
'createdAt',
])
.orderBy({ createdAt: 'desc' })
.execute();
複数列で並べ替え:
const notes = await client.data.Note.select([
'id',
'title',
'isPinned',
'createdAt',
])
.orderBy({ isPinned: 'desc' })
.orderBy({ createdAt: 'desc' })
.execute();
関係間を移動
@one()および@many()デコレーターとのリレーションシップを定義する場合は、同じクエリに関連エンティティ フィールドを含めることができます。
const notes = await client.data.Note.select([
'id',
'title',
'content',
'notebook.id',
'notebook.name',
])
.execute();
各ノートには、個別のクエリを必要とせずに、関連付けられているノートブック データが含まれています。
大きな結果セットの改ページ
大規模なリストにはカーソルベースのページネーションを使用します:
const page = await client.data.Note.select([
'id',
'title',
'createdAt',
])
.orderBy({ createdAt: 'desc' })
.orderBy({ id: 'asc' })
.first(25)
.executePaginated();
console.log('Items:', page.items);
console.log('Has next page:', page.hasNextPage);
console.log('End cursor:', page.endCursor);
カーソルを使用して次のページを取得します:
if (page.hasNextPage) {
if (!page.endCursor) {
throw new Error('The next page is missing its cursor.');
}
const nextPage = await client.data.Note.select([
'id',
'title',
'createdAt',
])
.orderBy({ createdAt: 'desc' })
.orderBy({ id: 'asc' })
.first(25)
.after(page.endCursor)
.executePaginated();
}
Note
バックエンドはtotalCountタイプ上のPagedResultプロパティを設定しません。
page.items.length値は現在のページのみをカウントし、すべての一致するレコードはカウントしません。
すべての一致するレコードを処理するには、hasNextPage が false になるまで先に進みます。 リクエストごとに選択、フィルター、ソート順は変更せずに管理してください。
let cursor: string | undefined;
let matchingRecords = 0;
while (true) {
let query = client.data.Note.select(['id'])
.where({ isArchived: { eq: false } })
.orderBy({ id: 'asc' })
.first(100);
if (cursor !== undefined) {
query = query.after(cursor);
}
const page = await query.executePaginated();
matchingRecords += page.items.length;
if (!page.hasNextPage) {
break;
}
if (!page.endCursor) {
throw new Error('The next page is missing its cursor.');
}
cursor = page.endCursor;
}
console.log('Records read across all pages:', matchingRecords);
ページングはリクエスト間のスナップショットを提供しません。 同時変更は、あなたが読み取るレコードやカウント結果に影響を与えることがあります。
データを集計してグループ化する
サーバー側の合計には aggregate() 、グループごとの要約には groupBy() を使いましょう。 スタンドアロンのフルーエント count() メソッドは利用できませんが、count は集約仕様内でサポートされています。
5つの集計演算(sum、 avg、 min、 max、 count)すべては数値フィールドを必要とします。 UUIDの id やテキストフィールドはカウントしないでください。 例えば、次のクエリは登録済み Product エンティティで必要な数値 stockQuantity フィールドを前提としています。
const totals = await client.data.Product.where({ isAvailable: { eq: true } })
.aggregate({
matchingProducts: { count: 'stockQuantity' },
totalStock: { sum: 'stockQuantity' },
averageStock: { avg: 'stockQuantity' },
lowestStock: { min: 'stockQuantity' },
highestStock: { max: 'stockQuantity' },
})
.execute();
console.log(totals[0].aggregations.matchingProducts);
count 指定された数値フィールドの非ヌル値をカウントします。 必要な数値フィールドを使って一致する行を数えます。 もし適切なフィールドがない場合は、先に示したように すべての ページにわたって識別子をカウントしてください。1ページだけではありません。
グループ合計:
const groups = await client.data.Product.groupBy(['status'])
.aggregate({
matchingProducts: { count: 'stockQuantity' },
totalStock: { sum: 'stockQuantity' },
})
.execute();
for (const row of groups) {
console.log(row.fields.status, row.aggregations.totalStock);
}
集約結果は fields オブジェクトと aggregations オブジェクトを含む配列です。 総計には空の fields オブジェクトを持つ行が1行あります。
count は number を返します。その他の操作は、空またはすべてが null の入力に対して number | null を返します。
集約する前にwhere()を適用します。 アグリゲーションを、select()、orderBy()、first()、またはafter()による行の選択、順序付け、またはページングと組み合わせてはいけません。
レコードを作成する
create() メソッドを使用して、新しいレコードを挿入します。
const newNote = await client.data.Note.create({
title: 'Meeting notes',
content: 'Discussion points from the team sync',
isPinned: false,
isArchived: false,
createdAt: new Date(),
updatedAt: new Date(),
user_id: 'user-123',
});
このメソッドは作成されたレコードを返し、自動生成されたIDidも含まれます。 追加の保存フィールドが必要な場合は、明示的な selected read を使用します。
リレーションシップを持つレコードを作成する
リレーションシップを持つエンティティを作成する場合は、関連する完全なオブジェクトまたは主キーのみを持つオブジェクトを渡します。
// Option 1: Pass just the ID
const note = await client.data.Note.create({
title: 'Weekly summary',
content: 'Summary of this week',
notebook: { id: '22222222-3333-4444-5555-666666666666' },
isPinned: false,
isArchived: false,
createdAt: new Date(),
updatedAt: new Date(),
});
// Option 2: Select the related fields you need before creating the note.
const notebooks = await client.data.Notebook.select(['id', 'name'])
.where({ id: { eq: '22222222-3333-4444-5555-666666666666' } })
.first(1)
.execute();
const notebook = notebooks[0];
if (!notebook) {
throw new Error('Notebook not found.');
}
const noteWithNotebook = await client.data.Note.create({
title: 'Weekly summary',
content: 'Summary of this week',
notebook,
isPinned: false,
isArchived: false,
createdAt: new Date(),
updatedAt: new Date(),
});
どちらの形式でも同じ結果が生成されます。 関連エンティティの ID が既にわかっており、余分なフェッチを回避したい場合は、最初のフォームを使用します。
クライアントは関連するオブジェクトのプライマリキーを使って関係を設定します。 オブジェクトを渡しても関連するノートブックは作成または更新されません。
レコードの更新
既存のレコードを変更するには、 update() メソッドを使用します。 フィルターオブジェクトと、更新するフィールドを含むオブジェクトを渡します。
await client.data.Note.update(
{ id: 'note-123' },
{
title: 'Updated title',
updatedAt: new Date(),
}
);
関係性の更新
リレーションシップを変更するには、新しい関連エンティティまたはその ID のみを渡します。
// Move a note to a different notebook
await client.data.Note.update(
{ id: 'note-123' },
{ notebook: { id: 'new-notebook-789' } }
);
レコードを削除する
フィルターに一致するレコードを削除するには、 delete() メソッドを使用します。
await client.data.Note.delete({ id: 'note-123' });
このメソッドは、バックエンドが削除を確認したときに解決されます。 フィルターに一致するレコードがない場合でも、メソッドは成功します。
レコードの作成または更新
upsert(where, create, update)を使って存在しないレコードを作成したり、既存のレコードを更新したりしてください。 検索とcreate入力で同じIDを入力してください:
const id = '11111111-2222-3333-4444-555555555555';
const now = new Date();
await client.data.Note.upsert(
{ id },
{
id,
title: 'Daily summary',
content: 'Summary of today',
isPinned: false,
isArchived: false,
createdAt: now,
updatedAt: now,
user_id: 'user-123',
},
{ title: 'Daily summary', updatedAt: now },
);
このヘルパーは読み取りを行い、その後に別途作成または更新を行います。 アトミックではなく、並行呼び出しは競合する可能性があります。 トランザクションや並行性の保証として使わないでください。
認証の処理
保護されたデータ操作を行う前にサインインしてください。 デプロイ済みのバックエンドでは、アプリが設定したMicrosoft Entraサインインフローを使いましょう。 以下のメールおよびパスワードの例はローカルバックエンド専用です:
await client.auth.signIn({ email, password });
// All subsequent data calls include authentication context
const notes = await client.data.Note.select(['id', 'title']).execute();
クライアントは、認証セッションをすべてのデータ API 呼び出しに自動的にアタッチします。 トークンを手動で渡す必要はありません。
ベスト プラクティス
- 必要なフィールドのみを選択 します。ペイロード のサイズを小さくし、パフォーマンスを向上させるために使用するフィールドのみをフェッチします。
-
大規模なリストではページネーションを使用する –
first()とexecutePaginated()を使用して、一度に何千件ものレコードを取得しないようにします。 - バッチ リレーションシップ クエリ – 個別の要求を行うのではなく、同じクエリに関連エンティティ フィールドを含めます。
- 頻繁にアクセスされるデータをキャッシュ する – API 呼び出しを減らすために、静的参照データをメモリに格納します。
現在の制限
- スタンドアロンの
count()メソッドは利用できません。 数値フィールドの集計を使用するか、すべてのページにわたってレコードをカウントします。 配列の長さは、そのページで返されたレコードのみをカウントします。 - 多対多リレーションシップはサポートされていません。 2 つの
@one()ナビゲーション デコレーターで明示的な結合エンティティを使用します。 -
totalCountのPagedResultプロパティは、バックエンドによって設定されません。