odata-execution

OData の実行

dxs odata execute を使って、OData クエリを段階的に作成、テスト、検証します。

参考資料

• references/filter-patterns.md — ラムダ演算子、文字列関数、SQL から OData へのマッピング

入出力の仕様

入力： 接続 ID ＋ エンティティの知識（フィールド名、ナビゲーションプロパティ — schema-explorer または会話のコンテキストから取得）

出力： 検証済みの OData クエリ文字列（ファイルではなく、会話のコンテキスト内）

ワークフロー — クエリを段階的に構築

クエリは一度に 1 層ずつ構築します。大きなクエリはタイムアウトし、expand を 1 つずつ追加すると問題の切り分けが容易になります。$select で 400 が返る場合は、フィールド名が間違っています。schema properties を確認し、$select を削除しないでください。

ステップ 1：$select を使ったベースエンティティ

ルートエンティティと、そのスカラー フィールドのみから始めます。

dxs odata execute -c <id> -q 'Entity?$top=1&$select=Id,Field1,Field2'

ステップ 2：1 対 1 の expand を追加

単一の関連エンティティを返すナビゲーションプロパティを追加します。

dxs odata execute -c <id> -q 'Entity?$top=1&$select=Id,Field1&$expand=Account($select=Id,Name),Status($select=Id,Name)'

ステップ 3：ネストされた expand を含むコレクションの expand を追加

ネストされた展開も含め、コレクションを返すナビゲーションプロパティを追加します。

dxs odata execute -c <id> -q 'Entity?$top=1&$select=Id,Field1&$expand=Lines($select=Id,LineNumber;$expand=OrderLine($select=OrderId;$expand=Material($select=Id,Name)))'

ステップ 4：すべてを組み合わせて完全なクエリを作成

検証済みのすべての層を結合し、最終クエリを作成します。$top=1 を削除するのは、この段階に限ります（ユースケースに適切な場合）。

サーバー側でフィルタリングする

クライアント側でのフィルタリングを受け入れる前に、そのロジックを $filter で表現できるか確認してください。OData は、コレクションのフィルタリング用のラムダ演算子、文字列関数、$expand 内のネストされた $filter をサポートしています。パターンの全一覧は references/filter-patterns.md を参照してください。

パラメーター化クエリ（キーセグメント）

単一エンティティのクエリでは、キーセグメント構文 Entity(0) を使います。0 はプレースホルダーです。まず Entity?$top=1 でクエリ構造を検証してから、Entity(0) に切り替えてください。

Entity(0) が 404 を返すのは想定どおりです（ID が 0 のエンティティが存在しません）。再テストに時間を費やさないでください。

# First: validate structure
dxs odata execute -c <id> -q 'Entity?$top=1&$select=Id,Field1&$expand=Status($select=Id,Name)'

# Then: switch to key segment
dxs odata execute -c <id> -q 'Entity(0)?$select=Id,Field1&$expand=Status($select=Id,Name)'

重要なルール

ルール	詳細
常に $top=1	タイムアウトを避けるため、テスト中に使用します
シングルクォート	-q には必ず '...' を使います（$ のシェル展開を防ぎます）
$expand 内の $select	すべての expand 句で必須です
ネストされたオプションの区切り文字	括弧内では & ではなくセミコロン（;）を使います
$select で 400 が返る	フィールド名が間違っています。schema properties を確認し、$select を削除しないでください
複合キー	keys: を確認してください。Id フィールドのないエンティティもあります

よくある間違い

間違い	修正方法
$select のない $expand	必ず $select=Field1,Field2 を含めます
$ の値にダブルクォートを使う	シングルクォートを使います。シェルはダブルクォート内の $ を展開します
クエリのテスト中に $top=1 を使わない	大きなクエリはタイムアウトします。開発中は必ず上限を設定します
Entity(0) をテストして 404 に慌てる	404 は想定どおりです。まず $top=1 で構造を検証してください
DXS-API-CONN / DXS-API-TLS / DXS-API-TIMEOUT / DXS-API-NET の後にクエリを書き直す	これらはクエリのエラーではなく、トランスポートの失敗です。ペイロードの suggestions[] に従ってください。configuration-roundtrip.md → Exit 141 とトランスポートエラー を参照してください