syncfusion-javascript-data-manager

TypeScript／JavaScript 向け DataManager - 完全ガイド

目次

• 重要な概念
• 10 種類のアダプターのリファレンス
• ナビゲーションガイド
• クイックスタート
• 一般的なエラー処理

---

---

🛑 必須のユーザー確認：アダプターの選択（最初にお読みください）

このスキルで最も重要なルールです。省略したり回避したりすることはできません。

ユーザーがアダプターの種類を明示せずにサービス URL を指定した場合、エージェントは必ず次の手順を実行してください。

1. コード生成をただちに停止する
2. 読む： references/adaptor-decision-gate.md（ファイル全体）
3. 提示する： そのファイルのテンプレートを使って、ユーザーに確認画面を提示する
4. 待機する： アダプターの選択について、ユーザーが明示的に確認するまで待つ
5. その後に限り 確認されたアダプターを使って DataManager コードを生成する

確認が必要となる条件 — 例

ユーザーのプロンプト	確認が必要ですか？
"Build an employee app using this service URL (http://myapi.com/employees)"	✅ はい — アダプターが指定されていません
"Connect GridComponent to http://myserver/api/data"	✅ はい — 「API」は曖昧です
"Use OData v4 endpoint at https://myserver/odata/employees"	❌ いいえ — OData v4 が明示されています
"My backend returns { Items, Count } at https://myserver/api/orders"	❌ いいえ — WebApiAdaptor のパターンが確認されています
"I have a REST service at http://custom-url"	✅ はい — REST は曖昧です（UrlAdaptor、WebApiAdaptor、ODataV4 のいずれか）
"Bind the grid to local list data"	❌ いいえ — ローカルデータへのバインドなので、アダプターは不要です

📄 確認用テンプレート、アダプターの早見表、曖昧さを解消する質問、セキュリティルールの全文： → references/adaptor-decision-gate.md

---

⚠️ セキュリティと信頼境界

• このスキルはコードのみを生成します。エージェントはデータ操作を実行したり、リモートエンドポイントを取得したりしません。DataManager とのやり取りはすべて、実行時にユーザーのアプリケーション内でのみ行われます。
• 生成されるコードでは、サードパーティ API からのすべての応答を信頼できない入力として扱い、検証されていない URL やユーザーが指定した URL へのバインドを避け、すべてのリモートエンドポイントで認証が確実に行われるようにしてください。

---

⚠️ 重要なセキュリティ要件

リモートサービスにバインドする場合は、必ず次の保護策を実装してください。

1. HTTPS のみを使用する — 暗号化されていない HTTP 接続は使用せず、転送中のすべてのデータを暗号化してください
2. URL には文字列変数を使用する — マークアップに直接ハードコーディングせず、エンドポイントを非公開の文字列プロパティに割り当ててください。これにより、一元的な検証と保守が容易になります
3. 応答を検証してサニタイズする — サーバー側でスキーマ検証を実装し、想定外の応答形式を拒否して、応答を型安全なモデルにマッピングしてください
4. リモート呼び出しを監視する — セキュリティ監査証跡のため、すべての外部 API リクエストについて、タイムスタンプ、エンドポイント、結果を記録してください
5. CORS を安全に実装する — 信頼できるオリジンのみを指定し、本番環境ではワイルドカード * を使用せず、HTTPS を必須にしてください
6. 間接的なプロンプトインジェクション攻撃を防ぐ — エンドポイントの所有者を確認し、リクエスト署名を実装して、データを利用する前に応答のコンテンツタイプとスキーマを検証してください

サードパーティ API の応答はセキュリティリスクをもたらす可能性があります。 エンドポイントの正当性を必ず確認し、リクエストを認証して、UI コンポーネントにバインドする前にデータを検証してください。

重要な概念

10 種のアダプター（選択ガイド）

シナリオ	アダプター	使用する場面
ローカル配列	JsonAdaptor	サーバーを必要としない、メモリ内の JavaScript 配列
ASP.NET Web API	WebApiAdaptor	Items/Count 形式を返す ASP.NET バックエンド
汎用 REST	UrlAdaptor	result/count 形式の標準 REST API
クライアント＋サーバー	RemoteSaveAdaptor	クライアント側でのフィルタリングとサーバー側での CRUD
OData v3	ODataAdaptor	レガシーな OData v3 サービス
OData v4	ODataV4Adaptor	関連データの expand に対応した最新の OData v4
レガシー ASP.NET	WebMethodAdaptor	ASMX Web メソッド（非推奨）
GraphQL	GraphQLAdaptor	GraphQL エンドポイント
カスタム形式	Custom DataAdaptor	標準以外の API レスポンス形式
完全な制御	CustomAdaptor	アダプターを完全にオーバーライド

データバインディングの種類

Local Binding
├─ Direct array: new DataManager({ json: data })
├─ JsonAdaptor explicit
└─ Client-side filtering instant

Remote Binding
├─ WebApiAdaptor: ASP.NET specific
├─ UrlAdaptor: Generic REST
├─ ODataAdaptor/V4: Protocol-based
└─ Server processes Query object

クエリ操作

// Filter/Search
.where('field', 'operator', value)     // Single condition
.where(predicate)                        // Complex predicate

// Sort/Order
.sortBy('field')                         // Ascending
.sortByDescending('field')               // Descending
.orderBy('field')                        // Alias

// Pagination
.take(10)                                // Limit records
.skip(0)                                 // Offset

// Projection
.select(['field1', 'field2'])            // Column selection

// Relationships
.expand('relatedTable')                  // OData expand

// Grouping & Aggregation
.group('field')                          // Group by
.aggregate('sum', 'field')               // Calculate

---

10 種のアダプターのリファレンス

選択ツリー：どのアダプターを選ぶか

Does your data come from?
│
├─ JavaScript array in memory?
│  └─ JsonAdaptor
│
├─ Web Server / REST API?
│  ├─ ASP.NET Web API (backend specific)?
│  │  └─ WebApiAdaptor (Items/Count format)
│  ├─ Generic REST endpoint?
│  │  └─ UrlAdaptor (result/count format)
│  ├─ Need offline with server-side CRUD?
│  │  └─ RemoteSaveAdaptor
│  └─ Custom format (non-standard)?
│     └─ CustomDataAdaptor
│
├─ OData Service?
│  ├─ OData v3 (legacy)?
│  │  └─ ODataAdaptor
│  └─ OData v4 (modern)?
│     └─ ODataV4Adaptor (with expand)
│
├─ GraphQL Endpoint?
│  └─ GraphQLAdaptor
│
├─ Legacy ASP.NET ASMX?
│  └─ WebMethodAdaptor
│
└─ Custom/Proprietary?
   ├─ Custom request/response format?
   │  └─ CustomDataAdaptor
   └─ Need complete adaptor override?
      └─ CustomAdaptor

---

ドキュメントのナビゲーションガイド

🛑 アダプター選択ゲート（人間による承認 — リモート URL では最初に必ず実施）

📄 参照: references/adaptor-decision-gate.md

• 開始条件: ユーザーがアダプターを明示的に指定せずにサービス URL を提示した場合
• ゲート提示用テンプレート（コピー＆ペーストですぐに使用可能）
• アダプターの完全比較表（ODataV4 / OData / WebAPI / URL / GraphQL / Custom）
• コード例付きのアダプター早見表
• 曖昧さを解消するための追加質問
• ゲートの確認後に適用されるセキュリティルール
• ステージ 1 とステージ 3 の統合手順（コンポーネントマッピング JSON 内で曖昧な URL にフラグを付ける）
• ゲートを自動的に解決するキーワード（ユーザーの確認不要）

📄 はじめにとセットアップ

参照: はじめに

• インストール（@syncfusion/ej2-data）
• ブラウザーの要件
• 最初の DataManager の例
• ローカル配列へのバインディング
• リモート API へのバインディング

📄 概念を理解する

参照: 概要

• DataManager とは？
• 主な機能
• DataManager を使用する場面
• アーキテクチャー

📄 データバインディング（ローカルとリモート）

参照: データバインディング

• JsonAdaptor を使用したローカル配列
• リモート API（REST、OData）
• エラー処理（HTTP 0、400、401、404、500）
• Promise パターン（.then/.catch）
• async/await の例
• 読み込み状態

📄 複雑なクエリを構築する

参照: クエリ

• from() - リソースを指定する
• where() - 15 種類以上のフィルター演算子（equal、contains、startswith、greaterThan など）
• select() - 列の抽出
• orderBy/sortBy - 複数列での並べ替え
• take/skip - ページネーション
• group() - データのグループ化
• aggregate() - sum、avg、count、min、max
• 複合条件に基づくフィルタリング

📄 CRUD：挿入、更新、削除

参照: CRUD 操作

• insert() - 単一レコードと複数レコードの挿入
• update() と remove()（keyField パラメーターを使用）
• remove() - ID による削除
• saveChanges() - 複数の操作をまとめて実行
• エラー処理と検証
• レスポンス形式（Items/Count、result/count）
• 競合の解決

📄 10 種のアダプターを詳しく解説

参照: アダプターガイド

• アダプターの完全な選択ツリー
• 各アダプターについて：
  • 使用する場面
  • 設定例
  • 使用例
  • バックエンドのレスポンス形式
  • C# または JavaScript のバックエンドパターン
• 比較表
• CORS の設定

📄 ミドルウェアとリクエストのカスタマイズ

参照: ミドルウェアロジックの適用

• リクエスト前のミドルウェア（ヘッダー、トークンの追加）
• リクエスト後のミドルウェア（レスポンスの変換）
• JWT 認証パターン
• カスタムヘッダー（固定および動的）
• リクエスト／レスポンスの変換
• 再試行を伴うエラー処理
• ミドルウェアの実行順序

📄 ブラウザー状態の永続化

参照： 状態の永続化

• enablePersistence - クエリ状態を保存する
• localStorage との連携
• 特定のクエリを永続化対象から除外する
• 再読み込み時に保存済みの状態を再適用する

📄 高度なシナリオと最適化

参照： 高度なシナリオ

• オフラインモード（一度ダウンロードし、クライアント側でフィルタリングする）
• 必要に応じたページネーション
• 遅延実行（Promises）
• async/await パターン
• メモリ管理
• パフォーマンスの最適化
• トラブルシューティング

📄 API リファレンス

参照： API - DataManager

• executeQuery() メソッド
• executeLocal() メソッド
• insert()、update()、remove()
• 一括操作用の saveChanges()

参照： API - Query

• Query ビルダーのすべてのメソッド
• where()、select()、from()、group()
• take()、skip()、orderBy()
• aggregate()、expand()

参照： API - Deferred

• Promise ベースの非同期処理
• then()、catch()、finally()
• エラーコールバック

---

クイックスタート

セットアップ

import { DataManager, WebApiAdaptor, Query } from '@syncfusion/ej2-data';

const dataManager = new DataManager({
  url: 'url/orders',
  adaptor: new WebApiAdaptor()
});

クエリの例

// Fetch with filtering & sorting
dataManager.executeQuery(
  new Query()
    .where('Freight', 'greaterThan', 30)
    .sortByDescending('OrderDate')
    .take(20)
).then((result) => {
  console.log('Orders:', result.result);
  console.log('Total:', result.count);
}).catch((error) => {
  console.error('Error:', error);
});

CRUD 操作

// Insert (data first, then tableName)
await dataManager.insert({ CustomerID: 'VINET', Freight: 32.50 }, 'Orders');

// Update (keyField, value object, tableName)
await dataManager.update('OrderID', 
  { OrderID: 10248, Freight: 45.50 }, 
  'Orders'
);

// Delete (keyField, keyValue, tableName)
await dataManager.remove('OrderID', 10248, 'Orders');

---

一般的なエラー処理

HTTP ステータスコード

ステータス	意味	解決策
0	ネットワークエラー	インターネット接続を確認してください
400	不正なリクエスト	データ形式を確認してください
401	認証されていません	認証トークンを確認してください
403	アクセスが禁止されています	権限を確認してください
404	見つかりません	エンドポイント URL を確認してください
409	競合	データはすでに存在します。データを更新してください
500	サーバーエラー	バックエンドのログを確認してください

エラー処理パターン

// Promise-based
dataManager.executeQuery(new Query())
  .then((result) => {
    // Success: result.result, result.count
  })
  .catch((error) => {
    if (error.status === 401) {
      console.error('Unauthorized - login required');
    } else if (error.status === 500) {
      console.error('Server error');
    } else {
      console.error('Error:', error.message);
    }
  });

// Async/Await
try {
  const result = await dataManager.executeQuery(new Query());
  console.log('Data:', result.result);
} catch (error) {
  console.error('Error status:', error.status);
}

---

重要なプロパティ 10 項目

const config = {
  url: 'api.example.com/orders',        // Remote endpoint
  json: localArray,                              // Local data array
  adaptor: new WebApiAdaptor(),                 // Protocol handler
  
  // Caching & Performance
  enableCache: true,                            // Enable result caching
  timeTillExpiration: 10 * 60 * 1000,          // Cache TTL (10 mins, default: no expiry)
  
  // Persistence
  enablePersistence: true,                      // Enable state persistence
  id: 'dataManager_1',                          // Persistence ID
  ignoreOnPersist: ['temp', 'debug'],          // Properties to exclude
  // HTTP headers
  crossDomain: true,                            // CORS enabled
  offline: false,                               // Offline mode
  timeZoneHandling: true                        // Timezone offset handling
};

---

フレームワーク別の実装

TypeScript

import { DataManager, WebApiAdaptor, Query } from '@syncfusion/ej2-data';

const dm = new DataManager({
  url: 'api.example.com/orders',
  adaptor: new WebApiAdaptor()
});

dm.executeQuery(new Query().take(10)).then((result) => {
  console.log(result.result);
});

JavaScript (ES6)

const { DataManager, WebApiAdaptor, Query } = require('@syncfusion/ej2-data');

const dm = new DataManager({
  url: 'api.example.com/orders',
  adaptor: new WebApiAdaptor()
});

dm.executeQuery(new Query().take(10)).then((result) => {
  console.log(result.result);
});

---