datasource-creator

Datasource Creator

Datex Studio 用の OData またはフローベースのデータソース設定を作成します。

参考資料

• ../datex-studio-shared/branch-setup.md -- ブランチと接続の選択（スキル間で共通）
• references/parameter-strategies.md -- パラメーター戦略、リンクされたデータソース、引用符のルール、カスケードパラメーター
• references/datasources.md -- データソースの分類：コンポーネントのバリアント（-datasource.json と -footprintDatasource.json）× クエリタイプ（OData とフロー）、呼び出し規約、階層の制限、埋め込みデータソース
• references/odata-datasources.md -- OData クエリタイプのプラットフォームリファレンス：queryOptions ツリー、フィルター式、展開、結果の型構造、事前スキーマ検証、標準スケルトン
• references/flow-datasources.md -- フロークエリタイプのプラットフォームリファレンス：ページ分割と単一結果の構造、getFlow/getListFlow/getByKeysFlow スロット、呼び出し構文、エンティティ定義の契約、標準スケルトン
• references/output-contracts.md — カウント、リンク、カスタム列、展開変換後の最終出力。コンポーネント出力とメソッド出力
• ../collection-filter-authoring/SKILL.md — オブジェクトコレクションを介した Any/All フィルターと、グリッド／ランタイムとの連携

依存関係

必須の事前知識： OData エンティティの探索については schema-explorer スキルを、クエリの構築と検証については odata-execution スキルを読んでください。

ODATA データソースでは、スキーマの探索が必須です — 型定義は、例やテンプレートだけではなく、検証済みのスキーマに基づいて作成する必要があります。フローデータソースは内部で OData クエリからデータを集約する場合がありますが、既存のデータソースを使用する場合は、検証済みであることを前提とします。

Footprint 接続 — 先に footprint-entity-expert を参照してください。 データソースが Footprint WMS エンティティ（Tasks、Shipments、ArchivedShippingLicensePlateContents、LicensePlate、Lot、Material など）をクエリする場合は、スキーマを探索する前に footprint-entity-expert を確認してください。ビジネス概念を裏付けるエンティティ、Owner／Project への正しいナビゲーションチェーン、重量計算の分岐、ページネーションの要件など、OData メタデータには現れない情報が記載されています。Footprint 以外の接続（カスタムアプリ、WMS 以外のデータ）では不要です。

前提条件の確認

スキーマ探索またはデータソース生成を始める前に、会話のコンテキスト内に要件ブリーフ（requirements-gathering または report-creator が作成したもの）がすでに存在するか確認してください。

• 要件ブリーフがある → それを使用してください。ブリーフには、探索するエンティティと含めるフィールドを決めるフィールド一覧、意味上の役割、ビジネスルールが記載されています。データソースの出力がブリーフに沿っていることを確認してください。
• 要件ブリーフがない → まず requirements-gathering スキルを実行してください。これは、datasource-creator が単独で（report-creator からではなく）呼び出された場合に該当します。ブリーフがあれば、必要なフィールドの見落とし、エンティティの誤ったマッピング、計算フィールドの省略を防げます。

この確認を省略しないでください。必要なフィールドとその意味を理解せずにデータソースを作成すると、設定が不完全になり、手戻りが発生します。

入力／出力の契約

方向	項目	詳細
入力	接続 ID	必須 -- Footprint API 接続を識別します
入力	ブランチ ID	必須 -- 検証とアップサートの対象ブランチです
入力	モード	owned（ホスティング先のグリッド／エディター／フォーム／レポートに埋め込む）または standalone（ブランチにアップサートする）。デフォルトは owned です。詳細は以下を参照してください
入力	データソースの種類	OData（クエリベース）または Flow（カスタム JS コード）
出力	JSON 設定ファイル	dxs datasource generate または generate-flow によって生成されます
出力（owned）	ファイルパス＋参照名	レポートの場合は、dxs report datasource add で --owned FILE:ALIAS とともに使用します。グリッド／エディター／フォームの場合は、ホストの datasources[] に組み込みます
出力（standalone）	アップサートされたデータソース	ブランチにアップロードされ、datasource-fields で検証され、テストデータが検出されます

モードのデフォルトは owned です。 呼び出し元がモードを指定していない場合は、データソースを owned として作成し、戻り値の概要でその旨を伝えてください。上書き条件に該当する場合に限り、standalone に切り替えてください。具体的には、2 つ目の利用者が同じクエリを本当に必要とする場合、利用者の種類が owned データソースに対応していない場合（セレクター、リスト、カレンダー、カード、ウィジェット）、フローデータソースから $datasources.<Package>.<name> を介して呼び出す必要がある場合、またはライブラリパッケージに含めて配布する場合です。ルールと上書き条件の全一覧は、references/datasources.md → デフォルトは Owned に記載されています。

モード別の手順

手順	Owned	Standalone
dxs datasource generate / generate-flow	はい	はい
dxs datasource context（型定義）	はい	はい
dxs datasource validate（ブランチに対して）	はい	はい
dxs configuration upsert datasource（ブランチへ）	いいえ	はい
datasource-fields（アップサート後の検証）	いいえ（レポートのアップロード後に実施）	はい
テストデータ／in_params の検出	いいえ（report-creator が処理）	はい

グリッド、エディター、フォームの場合、owned 列の手順は references/datasources.md → Owned データソースの作成 にある組み込み手順へ続きます。standalone のアップサートの代わりに、ホストを検証します。

ワークフロー

[requirements brief in context?]
        |
  +-----+-----+
  |            |
 YES          NO
  |            |
 use it    invoke `requirements-gathering` skill
  |            |
  +-----+------+
        |
[determine type: OData or Flow]
        |
  +-----+-----+
  |            |
 OData       Flow
  |            |
 schema ->   schema -> (REQUIRED: validate entities/properties
 query ->     the flow code will query against the connection)
 generate    create standalone OData datasources (generate + dxs configuration upsert datasource each)
  |          write type-def YAML (from validated schema, NOT from examples)
  |          write flow TS code (referencing $datasources.<RepoName>.<ref_name>)
  |          generate-flow
  |            |
  +-----+------+
        |
  context (dxs datasource context - get type defs)
  validate (dxs datasource validate - both modes)
        |
  +-----+-----+
  |            |
Standalone   Owned
  |            |
 dxs configuration upsert datasource
              return JSON file path
 fields       + ref name
 test data
 return ref

OData と Flow の使い分け

OData を使う場合	Flow を使う場合
必要なフィールドがすべてスカラーであるか、単一のナビゲーションプロパティを通じて取得できる場合（パスにコレクションが含まれない）	コレクションのナビゲーションプロパティのデータを、スカラーフィールドにフラット化する必要がある場合（例：OrderLookups または WarehousesContactsLookup をフラットフィールドとして含める必要がある、単一エンティティの出荷）
結果がテーブル／タブリックスに直接マッピングされるコレクションである場合（例：ShipmentLines）	複数の OData クエリを組み合わせるか、結合して単一の結果にする必要がある場合
シンプルなパラメーターによるフィルタリングで十分な場合	計算フィールドに複数のエンティティのデータ、またはカスタム集計が必要な場合
データが Footprint OData スキーマにある場合	行がクラウドの *-storage.json コンポーネントから取得され、$db を介して関数レイヤーで読み取られる場合（ストレージに対するグリッド／セレクター） — ../db-query/references/flow-db-datasources.md を参照

見分け方： dxs report datasource-fields <ref> --branch <id> を実行します（所有している場合は --report <ref>）。出力に collections: セクションがあり、必要なフィールドが単独のテキストボックス（テーブルではない）に含まれる場合は、Flow データソースを使います。OData データソースのコレクションは、フラットな DataSet フィールドとしてバインドできず、空白として解決されます。

本番環境でのパターン： 複雑なナビゲーションを使用する既存の Datex Studio レポート（梱包明細書、BOL、マスター BOL）は、すべてヘッダー／詳細データに Flow データソースを使用しています。Flow のコードは OData エンティティを取得し、コレクションをスカラーフィールドにフラット化します。OData データソースは、シンプルなリストクエリ（明細項目、ルックアップテーブル）に使用されます。

Flow データソースとスキーマの調査： Flow データソースは、スキーマ調査を省略するための近道ではありません。Flow データソースの JavaScript コードは通常、1 つ以上の OData エンティティにクエリを実行し、データを再構成します。型定義または Flow コードを記述する前に、必ず schema-explorer を使って、対象の接続に想定されるエンティティとプロパティがあることを検証してください。既存のレポート例やテンプレートが示すのは、ある接続で動作したことがある内容です。現在の接続で検証済みの設計ではなく、あくまで最初の仮説です。

呼び出し元に返す

ワークフローの完了後（単独実行または所有モードのいずれの場合も）、次の構造化された概要を呼び出し元のスキルまたはユーザーに返します。

1. 参照名 — -r の値（例：ds_shipment_bol）
2. ファイルパス — -o の出力パス（例：reports/bol/ds_shipment_bol.json）
3. モード — owned（ローカルファイル。ホストの datasources[] に挿入するか、--owned で登録します）または standalone（アップサート済み）。どちらかを明記し、standalone の場合は、それを正当化するオーバーライドも記載します
4. 結果の種類 — single または collection（生成された設定の resultIsCollection に基づきます）
5. in_params — 入力パラメーター名と型の一覧（設定の inParams に基づきます）。ない場合は空にします
6. フィールドの概要 — データソースのコンテキストと、永続化後の datasource-fields に基づいて、確定した公開 result を説明します。カスタムフィールドとリンクフィールドを含め、コレクションには印を付けます。queryOptionsObjectTypeDef だけでは基底エンティティしか表せず、拡張フィールドが省略される場合があります。output-contracts.md を参照してください。

返答例：

Datasource: ds_shipment_bol
File: reports/bol/ds_shipment_bol.json
Mode: owned
Result type: single
in_params: shipmentId (number)
Fields:
  Id: number (key)
  BillOfLading: string
  LookupCode: string
  Carrier.Name: string
  Carrier.ScacCode: string
  Status.Name: string
  ShipmentLines [collection]:
    LineNumber: number
    OrderLine.Material.LookupCode: string
    OrderLine.Material.Description: string

返答にコレクションフィールドが含まれる場合、呼び出し元による対応が必要です。 フィールドの概要に [collection] マーカーが含まれる場合、呼び出し元は次のいずれかを選択する必要があります。

1. フローデータソース（推奨）： コレクションをスカラーフィールドにフラット化するフローとしてデータソースを書き換えます。コレクションを含まないフラットなフィールド一覧を取得できます。
2. 子データセット（代替案）： レポートに、CommandText: "$.ds_name.result.CollectionPath.*" を指定した別の DataSet を作成し、スタンドアロンのテキストボックスで =First(Fields!Field.Value, "child_dataset") を使用します。動作しますが、複雑さが増します。
3. 別の OData データソース： コレクションエンティティを独自のデータソースとして直接クエリします（例：ShipmentOrderLookups?$filter=ShipmentId eq {id}）。エンティティが直接のフィルター処理に対応している場合に限り使用できます。

コレクションパスのフィールド（例：OrderLookups.Order.OwnerReference）を、単一結果の DataSet のフラットなフィールドとして dxs report dataset add --field に渡しては絶対にいけません。その場合、値は警告なく空白で表示されます。

OData データソースの生成

プラットフォームのリファレンス： references/odata-datasources.md では、基盤となる Datex Studio のファイル形式について説明しています。内容は、queryOptions ツリー、フィルター式の構文、展開、結果型の契約、単一オブジェクトとコレクションに関する注意点、標準的なひな形です。生成された設定がなぜその構造になるのかを検討する場合、ジェネレーターを使わずに JSON を作成または手動編集する場合、あるいはインポートエラーをデバッグする場合に参照してください。

dxs datasource generate で OData データソース設定を生成します。

dxs datasource generate \
  -c <connection_id> \
  -q '<odata_query>' \
  -r <reference_name> \
  -t "<reference_name>" \
  -d "<description>" \
  --api-setting-name <app_level_name> \
  -o ds_name.json \
  --branch <branch_id>

主なフラグ

フラグ	目的
-c	接続 ID
-q / -Q	OData クエリ文字列／クエリファイル（同時に指定できません）
-r	参照名（有効な JS 識別子。ds_ プレフィックスの使用を推奨）
-t	表示タイトル（-r と一致する必要があります。「命名規則」を参照）
-d	説明（必ず指定してください）
--api-setting-name	dxs source branch settings のアプリレベル設定 name（DSV などの接続名ではありません）。省略可能です。省略すると、CLI は -c の接続名と apiConnectionName が一致する設定を照合して自動解決します（ホストと ComponentModule のブランチで動作します）。複数の API 接続設定がある場合に曖昧さを解消するときのみ、明示的に指定してください。
--param-keys	Entity(0) パターンを使う単一エンティティクエリ用
--detect-params	${$datasource.inParams.paramName} 構文を使ってフィルターパラメーターを検出します（required: false を設定し、ガードを付与します）
--dynamic-filter PROP:TYPE	任意の UI フィルタリング（$utils.isDefined() ガード付きの条件付きフィルターを生成します）
--dynamic-orderby PROP	任意の UI ソート
--param-filter PROPERTY:OPERATOR:PARAM_NAME:TYPE	$utils.isDefined() ガード付きの条件付きフィルター。演算子：eq、ne、gt、ge、lt、le、in、contains、startswith、endswith
--linked name:type:target	リンクされたデータソース。oneToOne／oneToMany は 3 パート、oneToOneWithMerge は $entity.Field を含む 4 パートです
--linked-param LINKED_NAME:PARAM_ID:EXPRESSION	親フィールドをリンク先データソースの入力パラメーターにマッピングします
--custom-column	計算列を追加します
--private	アクセス修飾子を private に設定します（デフォルト：public）
-o	出力ファイルのパス
--branch	対象ブランチ ID

パラメーターの選択方法

用途	フラグ	クエリ構文
1 つのエンティティ（詳細／ドキュメント）に範囲を限定する	--param-keys	Entity(0)?$select=...
レポートから渡されるフィルターパラメーター	--detect-params	$filter で ${$datasource.inParams.paramName} を使います。required: false を設定し、全体を $utils.isDefined() でガードします。下記の注記を参照してください
任意の UI リストフィルタリング	--dynamic-filter PROP:TYPE + --dynamic-orderby PROP	Entity?$select=...（プレースホルダーなし）
ガード付きの条件付きフィルター	--param-filter PROPERTY:OPERATOR:PARAM_NAME:TYPE	追記される述語にのみ $utils.isDefined() ガードを自動生成し、ベースの -q フィルターは無条件のままにします

フローデータソースの生成

プラットフォームリファレンス： references/flow-datasources.md では、基盤となる Datex Studio のファイル形式について説明しています。ページネーションありと単一結果の実行形式、getFlow／getListFlow／getByKeysFlow スロット、referenceName を使った呼び出し構文、エンティティ定義の出力コントラクト、両形式の標準的なスケルトン（列挙型ドロップダウンのパターンを含む）が記載されています。ユースケースで必要な形式を判断するとき、ジェネレーターを使わずに JSON を作成するとき、または実行時にフィールドが何も表示されずに undefined になるときに参照してください。

Flow のランタイムモデル（重要）

フローのデータソースは、正規の2つのソースのいずれかからデータを取得します。生の OData クエリ文字列を使うことはありません。（a）ブランチ上にすでに存在するスタンドアロン OData データソース。$datasources.<RepoName>.<ref_name> 経由で参照します（以下で説明します）。または（b）クラウドストレージ。関数層の $db.<Package>.<storage_referenceName> 述語 API 経由で参照します。これは *-storage.json コンポーネントを使ったグリッドやセレクターの背後で使用されるパターンです。$db の経路には独自の作成ルール（ページング、動的なフィルター／ソート、getQuery() ファクトリー）があります。詳しくは ../db-query/references/flow-db-datasources.md を参照してください。このセクションの残りでは、ソース（a）について説明します。

フローのデータソースコードは、生の OData クエリを実行しません。代わりに、フローでは $datasources オブジェクトを使って、ブランチ上にすでに存在するスタンドアロン OData データソースを参照します。スタンドアロンデータソースは、リポジトリモジュール名（リポジトリの uniqueIdentifier 名。例：PurchaseOrders、AsnOrders）の下にスコープされるため、パスは $datasources.<RepoName>.<ref_name> です。

// CORRECT: Reference standalone OData datasources with module scope, unwrap .result
const shipmentResp = await $datasources.PurchaseOrders.ds_shipment.get({ shipmentId: $flow.inParams.shipmentId });
const shipment = shipmentResp.result;
// For collection datasources, .result is an array:
const contactsResp = await $datasources.PurchaseOrders.ds_wh_contacts.get({ warehouseId: shipment.ActualWarehouse.Id });
const firstContact = contactsResp.result?.[0]?.Contact;
// Set output via $flow.outParams.result
$flow.outParams.result = { Name: shipment.Name, Phone: firstContact?.PrimaryTelephone };

// WRONG: Missing module scope — datasources are not at the root level
const result = await $datasources.ds_shipment.get({ shipmentId: 123 });

// WRONG: Raw OData queries in flow code — this is NOT how flows work
const result = await $datasource.getList({ query: 'Shipments(123)?$expand=Carrier' });

フローコードのランタイム変数：

変数	用途
$flow.inParams	フローのデータソースの入力パラメーターにアクセスします
$flow.outParams.result	フローの出力を設定します（値を代入し、return は使いません）
$datasources.<RepoName>.<ref_name>	ブランチ上のスタンドアロンデータソースにアクセスします（リポジトリ名でモジュールのスコープが決まります）

レスポンスのアンラップ： すべての $datasources 呼び出しは { result?: ... } を返します。--param-keys データソースの場合、result は単一のオブジェクトです。コレクションデータソースの場合、result は配列です。フィールドにアクセスする前に、必ず .result を参照してください。

フローデータソースを作成する手順：

1. フローに必要なクエリごとにスタンドアロン OData データソースを作成します。それぞれに dxs datasource generate と dxs configuration upsert datasource を使用します
2. $datasources.<RepoName>.<ref_name>.get() または $datasources.<RepoName>.<ref_name>.getList() を使ってそれらのデータソースを参照するフローコードを記述します（<RepoName> は dxs source repo list に表示されるリポジトリの name です）
3. dxs datasource generate-flow でフロー設定を生成します。フローコードと型定義が埋め込まれます
4. フローデータソース自体は、デフォルトで所有型（ホストに埋め込み）ですが、その OData 依存関係はブランチ上のスタンドアロンである必要があります。$datasources.<RepoName>.<ref_name> はスタンドアロン設定に対してのみ解決されるため、埋め込みの依存関係はフローコードから到達できません。これは references/datasources.md → デフォルトで所有型 に記載された恒常的な例外の1つです。

$datasources API：

メソッド	使用するケース	戻り値
$datasources.RepoName.ds_name.get({ paramName: value })	OData データソースが --param-keys を使用する場合（単一エンティティ）	単一のオブジェクト
$datasources.RepoName.ds_name.getList({ paramName: value })	OData データソースがコレクションを返す場合	オブジェクトの配列

入力パラメーターはオブジェクトとして渡してください。キーは OData データソースの inParams と完全に一致する必要があります。

大量レコードを扱うコレクションデータソースのページネーション

OData のレスポンスは、1 リクエストあたり 5,000 レコードに制限されています。Tasks、ArchivedShippingLicensePlateContents、Shipments、またはその他のエンティティを日付範囲や複数の倉庫にわたって集約するフローでは、明示的にページネーションを行う必要があります。自動的な継続処理はなく、データが切り捨てられても通知されません。

ページネーションを行うには、フローが呼び出すスタンドアロン OData データソースで skip inParam を宣言し、クエリで $top=5000&$skip=${$datasource.inParams.skip} を使用する必要があります。その後、フローで getList({ ..., skip }) を使ってループし、短いページが返されたら終了します。

全体のパターン（データソースのクエリ形式、--detect-params の要件、標準的な取得ループ）については、../datex-studio-shared/flow-code-patterns.md#odata-pagination--the-5000-record-cap を参照してください。基盤となるクエリが 5,000 行を超える可能性のあるフローデータソースを作成する場合は、最初からページネーションを組み込んで OData データソースを作成してください。後から対応するには、データソースとフローコードの両方を再生成する必要があります。

--param-keys が作成するのは名前付きパラメーターであり、keys 配列ではありません。 OData データソースで --param-keys（例：Shipments(0)）を使うと、ジェネレーターはエンティティキーにちなんだ名前の inParams（例：shipmentId）を作成します。正確なパラメーター名を確認するには、生成された設定の inParams を必ず確認してください。決して { keys: [value] } を使わないでください。この形式は存在しません。

// CORRECT: Use the actual inParam name from the generated config
const resp = await $datasources.ds_shipment.get({ shipmentId: $flow.inParams.shipmentId });

// WRONG: There is no "keys" parameter — this causes TS compilation errors
const resp = await $datasources.ds_shipment.get({ keys: [$flow.inParams.shipmentId] });

生成コマンド

dxs datasource generate-flow を使ってフローデータソースの設定を生成します。

dxs datasource generate-flow \
  -r ds_lookup -t "ds_lookup" -d "Custom lookup datasource" \
  --type-def types.yaml \
  --get-flow get.ts \
  --in-param id:number \
  -o ds_lookup.json --branch <branch_id>

必須： 少なくとも 1 つのフローメソッド（--get-flow、--get-list-flow、--get-by-keys-flow のいずれか）と、型定義ファイル（--type-def）が必要です。

主なフラグ

フラグ	用途
--type-def FILE	出力型の構造を定義する YAML／JSON ファイル（必須）
--get-flow FILE	単一エンティティを取得する JavaScript コード
--get-list-flow FILE	コレクションを取得する JavaScript コード
--get-by-keys-flow FILE	キーに基づいて取得する JavaScript コード（--key が必要）
--on-init-flow FILE	初期化用の JavaScript コード
--in-param NAME:TYPE	入力パラメーター（省略可能にするには ? を付加します。例：search:string?）。複数回指定できます
--key NAME:TYPE	キーフィールドの定義。複数回指定できます
--collection	resultIsCollection=true に設定します
--single	resultIsCollection=false に設定します

型定義の YAML 形式

- id: Id
  type: number
- id: Name
  type: string
- id: Items
  type: object
  isCollection: true
  objectTypeDef:
    - id: LineNumber
      type: number

有効な型：string、number、boolean、date、object、union、blob。

拡張フラグ（--dynamic-filter、--linked、--custom-column など）は、OData データソースと同様に機能します。コレクションナビゲーションパスには、collection-filter-authoring を使用してください。どちらのジェネレーターも、明示的なドット区切りの --dynamic-filter パス、またはコレクションを自動的に走査する --all-dynamic-filters --include-collection-filters を受け付けます。

ファイルサイズの上限： すべてのコードファイルと型定義ファイルの上限は 512 KB です。

サーバーティアのバリアント（FPDS — -footprintDatasource.json、typeId 19）

上記の内容で生成されるのは、関数とセレクターから呼び出し可能な、クラウドの-datasource.json（configurationTypeId: 6）です。データソースをアクションから呼び出す必要がある場合（Footprint サーバーティア）は、代わりに**FootprintDatasource（FPDS）**のバリアントを作成してください。OData とフローのどちらのクエリータイプでもサポートされています。本文の形状はクラウドのバリアントと同じで、変わるのはバリアントのフィールドだけです。

ジェネレーターには FPDS 用のフラグはありません。上記のとおり設定を生成してから、生成された JSON を編集してください。

• OData FPDS：configurationTypeId: 19を設定します。apiSettingNameにはすでにブランチの Footprint API 接続名が設定されています（generateによって設定）。そのままにしてください。（変更は 1 フィールドのみです。）
• フロー FPDS：configurationTypeId: 19を設定し、さらにapiSettingNameにブランチの Footprint API 接続設定名を設定します（generate-flowではnullのままです。名前はdxs source branch settings <branch_id>で確認してください。通常はFootprintApiですが、ブランチによって異なる場合があります。例：fpapiconn）。

その他のすべての項目（queryOptions／フロースロット、outParams、keyDef、明示的なnullスロット）は、クラウドのバリアントと同じです。references/datasources.md → バリアント間の構造上の差異を参照してください。

検証とプッシュには**footprintdatasource** CLI タイプを使用してください（dxs datasource …／dxs configuration upsert datasourceの経路はクラウドのdatasource／6 エンドポイントに固定されており、typeId 19 は出力できません）。

dxs configuration validate footprintdatasource -b <branch_id> -D ds_name.json   # exit 1 = errors found
dxs configuration upsert  footprintdatasource -b <branch_id> -D ds_name.json

upsertはreferenceNameで解決します（作成または更新）。削除するにはdxs configuration delete footprintdatasource <id> -b <branch_id> -yを実行してください。

セレクターの基盤に FPDS を使用してはいけません。セレクターの基盤には、クラウドの-datasource.jsonバリアントを使用してください（references/datasources.mdを参照）。FPDS はアクションティアの呼び出し元を対象としています。

コンテキストコマンド

バックエンドとフロントエンドのシンボルのフィルタリングを含む、コンテキスト応答の取得と読み取りに関する完全なガイドは、../datex-studio-shared/context-navigation.mdを参照してください。コンテキスト全体を解析せずに$types.<Package>.*カスタム型や列挙型メンバーの存在をすばやく確認するには、そこで説明されているnomenclatureレジストリを使用してください。

dxs -O json datasource context <file.json> --branch <branch_id>

式や TypeScript コードを作成するためのデザイナー型定義を返します。OData とフローの両方のデータソースで動作します。カスタム列やフローコードを記述する前に、利用可能なフィールドを確認するため、generate／generate-flowの実行後に実行してください。

データソースでは、主なスコープシンボルは$entity、$ccentity、$datasourceです（flowContextまたはlinkedDatasourcesContext内）。appContextには追加のサービスが含まれています。利用可能なサービスを確認するにはdefaultContext.importsを読み取ってください（共有リファレンスを参照）。

検証

dxs datasource validate <file.json> --branch <branch_id>

データソースの設定をブランチに対して検証します。upsert またはレポートのアップロードに進む前に、スタンドアロンモードと所有モードの両方で実行してください。このコマンドはデータソースを単独で検証するため、利用側の形式との不一致は検出できません。そのため、どの利用側でも使えない形式のデータソースでも、ここでは検証に合格します。

ブランチでは、サーバー側で2 つの独立したゲートが実行されます。どちらも公開時と dxs configuration validate の実行時に動作しますが、このコマンドで代替できるのは一部だけです。

• 利用ゲート — グリッド／セレクターには getList と getByKeys が必要です。エディター／フォームには単一の結果を返す get が必要です。各 linkedDatasources エントリーは、リンクの type と一致している必要があります（references/flow-datasources.md → リンクされたデータソースのリンクタイプを参照）。このゲートが動作するのは、利用側を検証するとき（dxs configuration validate <consumer type>）だけです。そのため、データソース単独の検証では何もわかりません。
• 分離ゲート — データソース自体の形式を検証します。そのため、これまでは問題なく公開できていた、利用側がまったく存在しない形式不正のデータソースも、現在は公開できません。FootprintDatasource の設定にも適用されます。フロースロットのルールはこのリポジトリで説明している範囲であり、このコマンドのローカル lint ではオフラインでそのルールを再現します。詳細は references/flow-datasources.md → 3 つの実行形式を参照してください。このゲートでは OData クエリオプションと最終出力コントラクトも検証します。CLI でも、出力の整合性をローカルで検証するようになりました。生成では、拡張処理とリンク解決の後に出力が確定されます。

フィルター付きクエリについて、このコマンドで検証できない点が2 つあります。どちらも upsert の前に確認しておく価値があります。フィルター列にインデックスが設定されているかどうか、および実行時にクエリの範囲を限定する述語が消える可能性があるかどうかです。フィルターをパラメーター化する generate フラグはすべて、フィルターを $utils.isDefined() ガードで囲みます。そのため、パラメーターがない場合は失敗せず、テーブル全体を対象にします。詳細は references/odata-datasources.md → こちらも確認してください：フィルター列にインデックスが設定されていますか？と→ ガード付きのスコープフィルターによってインデックスの確認が無効になりますを参照してください。

レポートの読み方

このコマンドはローカルのフロー構造と出力コントラクトのチェックを実行し、その結果をサーバーの結果と統合するため、1回の実行で両方を報告します。各項目には4つのフィールドがあります。

フィールド	値	意味
origin	local | server	どのチェッカーが生成したかを示します。local は CLI 独自のリンターによる結果（オフラインで再現可能）です。server はブランチから取得したもので、ブランチの変更に応じて変わることがあります。
severity	error | warning	エラーは処理をブロックし、警告は参考情報です。
source	—	どのルールまたはサブシステムが指摘したかを示します。
message	—	指摘内容です。

終了コード：

• ローカルまたはサーバーでエラーが1つでもある場合 → 終了コード 1。validation_errors[] には、エラーと警告を統合したリストが格納されます。この非ゼロの終了コードは、検証でエラーが見つかったことを意味します。ペイロードを確認し、設定を修正してから再検証してください。CLI が壊れたことを意味するものではなく、コマンドを変更せずに停止したり再試行したりする理由にはなりません。
• 警告のみの場合 → 終了コード 0。validation_result: {status: "valid", warnings: [...]} が返されます。ブロックされることはありませんが、警告の内容は確認してください。

dxs configuration validate datasource と dxs configuration validate footprintdatasource は同じローカルリンターを実行し、同じ統合形式で結果を報告します。この2つのコマンドは意図的に同期されています。その他の設定タイプでは、サーバーの指摘のみを報告します。CLI 全体の終了コードの一覧（エラーがあっても終了コード 0 を返す dxs function validate を含む）については、../datex-studio-shared/configuration-roundtrip.mdを参照してください。

ローカルで指摘が見つかっている状態でサーバー呼び出し自体が失敗した場合、レポートにはローカルの指摘が保持され、origin: server の validate API call failed (…) 項目が追加されます。ローカルの指摘は依然として有効であり、修正する価値があります。

スタンドアロンの完了

検証に合格したら、スタンドアロンのワークフローを完了します。

1. Upsert

dxs configuration upsert datasource -D <file.json> --branch <branch_id>

2. フィールドの確認

dxs report datasource-fields <reference_name> --branch <branch_id>

出力で次の項目を確認してください：

1. in_params の名前 -- --datasource-param と完全に一致する必要があります（id と決めつけないでください）
2. result_type -- single と list のどちらかによって、レポートのレイアウトが変わります
3. collections -- テーブルセクションで使用できるナビゲーションプロパティのコレクションです
4. フィールドパス -- 式で使う正確なドット記法のパスです

3. テストデータの検出

テンプレートリテラルのパラメーターを使わず、基本フィルターに $top=5 と $orderby を加えてエンティティをクエリし、最近のレコードを探します。

dxs odata execute -c <id> \
  -q 'Entity?$top=5&$filter=<base_filters>&$select=Id,<param_fields>&$orderby=<date_field> desc'

件数は $count=true&$top=1 で確認します。

dxs odata execute -c <id> \
  -q 'Entity?$count=true&$top=1&$filter=<full_filter_with_real_values>&$select=Id'

4. データソースの削除

参照名または設定 ID を指定して削除します。

dxs datasource delete ds_my_report --branch <branch_id>
dxs datasource delete --id 42 --branch <branch_id>

参照名による検索で 404 が返される場合は、--id を使用してください（コンポーネントモジュールを含むブランチで発生することがあります）。ID は dxs datasource list で取得します。

命名規則（重要）

データソースの参照名（-r）、表示タイトル（-t）、RDLX-JSON の DataSet 名、および --owned のエイリアスは、すべて同一でなければなりません。

-r ds_my_report -t "ds_my_report"              # generate: -t = -r
DataSet.Name = "ds_my_report"                  # RDLX-JSON
--owned ds_my_report.json:ds_my_report         # report datasource add: file:alias

ルール：

• ds_ 接頭辞の規則を使用します
• 有効な JS 識別子である必要があります（英字／_／$ で始まり、スペース／ハイフンを含まず、数字で始まらないこと）
• 例：ds_shipment_bol、ds_orders、ds_inventory_summary

主なルール

• schema batch を使用して、複数のスキーマ検出呼び出しを、9回以上の逐次呼び出しではなく2～3回のリクエストにまとめます
• 複合キーを確認します。一部のエンティティでは複数フィールドのキーが --param-keys の動作に影響します
• クエリのテスト時は $top=1 を使用します。上限を設けないと、大きなクエリはタイムアウトします
• $ の値にはシングルクォートを使用します。シェルはダブルクォート内の $ を展開するため、-q、--linked、--custom-column、--datasource-param、--linked-param にはシングルクォートを使います
• $expand には必ず $select を含めます。$select のない $expand は、すべてのフィールドを取得します

よくある間違い

間違い	修正
マネージャー接続名を --api-setting-name として使う	branch settings のアプリレベルの name を使うか、フラグを省略して CLI にブランチの AppConfig から自動解決させてください
branch settings の出力から apiConnectionId を探す	その必要はありません。AppConfig 設定レコードでは、apiConnectionName にある 名前 で接続を識別します。-c で指定した接続名と apiConnectionName が一致する設定を見つけ、その設定の name を --api-setting-name に指定してください（またはフラグを省略して自動解決させてください）。レコードの形式と列挙型のシリアライズに関する注意点については、../datex-studio-shared/branch-setup.md を参照してください
generate で API 設定の解決に失敗した際に、何も考えずに再試行する	DXS-DS-021 エラーは、-c で指定した接続がブランチ上の Footprint API 設定に紐付けられていないことを意味します。--api-setting-name を明示的に指定する（dxs source branch settings で確認）か、Studio で接続をブランチの AppConfig に紐付けてください。同じコマンドを再実行してはいけません
別のブランチ／アプリからデータソース設定 JSON をコピーし、そのまま upsert する	apiSettingName は アプリスコープ です。コピーした値は、対象アプリで定義されていない設定を指している可能性があります。upsert は警告なしで受け入れますが、その後 Studio に「Missing API Connection setting <name>」と表示されます（CAC では dxs ng push の DXS-NG-047 プリフライトチェックが失敗します）。最初に dxs source branch settings <target-branch> を確認するか、対象ブランチに対して dxs datasource generate で再生成してください（自動解決されます。接続が紐付けられていない場合は DXS-DS-021 になります）。アプリに API 接続がない場合は、Studio で接続を紐付けてください。CLI が接続を作成することはありません
フィルターで ${$datasource.inParams.Param} ではなく {Param} を使う	--detect-params ではテンプレートリテラル構文が必要です。単純な {curly braces} は無視されます
レポートから渡されるパラメーターに --dynamic-filter だけを使う	動的フィルターは任意の UI フィルターです。レポートから渡されるパラメーターには、テンプレートリテラルとともに --detect-params を使ってください
--detect-params によってパラメーターが必須になると思い込む	required: false が設定され、$filter 全体にガードが付与されます。必須かつガードのないフィルターを生成するフラグはありません。述語によってクエリの範囲が限定される場合は、JSON の required: true を修正するか、コンシューマー側で範囲を強制してください。references/odata-datasources.md を参照してください
upsert 後に in_params を確認しない	必ず datasource-fields を実行し、in_params に値が設定されていて空ではないことを確認してください
inParam 名が id だと思い込む	datasource-fields の出力を確認してください。shipmentId、orderId などの場合があります
データソースの -t タイトルが -r の参照名と異なる	タイトルと参照名は同一でなければなりません（例：-r ds_foo -t "ds_foo"）
リンク先が存在しない、またはカーディナリティ／キーに互換性がない	生成前に実際のブランチ上のリンク先を特定し、その形状を修正してください。output-contracts.md を参照してください
生成される出力はベースエンティティのフィールドだけだと思い込む	リンク／カスタム列や OData の件数を含む確定済みの契約を使い、コンシューマー側にも反映してください
oneToOne で mergeByValue を使う	4 番目のコンポーネントを取得するのは oneToOneWithMerge だけです
フィルターに日付をハードコードする	動的な値には ${new Date(...).toISOString()} を使ってください
フローコード内で生の OData クエリを使う	フローコードでは、$datasources.RepoName.ds_name.get() ／ .getList() を使ってスタンドアロンのデータソースを参照してください。OData クエリ文字列を埋め込んではいけません
モジュールスコープなしで $datasources.ds_name を使う	スタンドアロンのデータソースはリポジトリモジュールのスコープ内にあります。$datasources.RepoName.ds_name を使ってください（例：$datasources.PurchaseOrders.ds_shipment）。モジュールのプレフィックスがないと、フローバリデーターは「Property does not exist on type 'IDatasourceService'」と報告します
ブランチ上にスタンドアロンの OData 依存関係がないフローデータソースを使う	先に OData データソースを作成して upsert し、その後、それらを参照するフローを作成してください

---

編集後、post-edit-verificationを実行して、説明文／JSON／スキーマの違反を検出してください。最終レビューでは、component-validatorを実行してください。