Fabric Apps での GraphQL を使用したデータの読み取りと書き込み

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 プロパティは、バックエンドによって設定されません。