> ## Documentation Index
> Fetch the complete documentation index at: https://www.integrate.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# ETL: Extended JSON extractionによるネスト構造の展開
> Integrate.io ETLのREST API Sourceが新たにサポートするExtended JSON extraction機能を使い、ネストされたJSONレスポンスから必要なフィールドだけを平坦化して取り出す方法を解説します。
REST API からデータを取得してパイプラインに組み込みたいケースは、ETL 業務で非常に多いシナリオです。しかし、レスポンスのJSONは入れ子のオブジェクトや配列を含む複雑な構造になっていることが多く、**「必要なフィールドだけを平坦化して取り出す」作業に手間がかかります**。
Xplentyの**Rest API Source**コンポーネントは、HTTP エンドポイントからのデータ取得、認証、ページネーション、そしてレスポンスのパースまでをローコードで完結できるソースコンポーネントです。
新たに加わった**Extended JSON extraction**機能を使えば、ネストされたJSONのフィールドをスキーマ上で直接選択・展開でき、後続コンポーネントにフラットなデータとして渡すことが可能になります。
本記事では、Rest API Source のExtended JSON extractionの実践的な使い方までを解説します。
## Rest API Sourceの概要
Rest API Source は、REST Web サービスなどの HTTP エンドポイントからデータを読み取るためのコンポーネントです。パッケージデザイナー上で以下の要素を定義するだけで、API データの取り込みパイプラインを構築できます。
* ステップ１：認証方式
* 認証なし
* Basic 認証
* Connection
* ネイティブコネクターによる認証は、Connectionで該当の**ネイティブコネクター**を選択
* 他のOAuth認証は、Connectionで設定済みの**Universal OAuthコネクター**を選択
* ステップ２：リクエストとレスポンスの設定
* リクエストの設定（HTTP メソッド、URL、ヘッダー、ボディ）
* ページネーションの設定
* レスポンスのパース方式
* Extended JSON extractionの使用有無
* ステップ３：入力フィールドの選択
* フィールド選択
* Extended JSON extractionの有効時に追加のフィールド選択(タブー形式)
* データプレビュー
## Extended JSON extraction：ネストされたJSONを直接展開
### Extended JSON extraction とは
通常の JSON パースでは、レスポンスの第 1 階層のキーのみがフィールドとして認識されます。たとえば、以下のような API レスポンスがあった場合を考えてみましょう。
```json theme={null}
{
"id": 1,
"name": "Example",
"address": {
"city": "Tokyo",
"zip": "100-0001"
},
"tags": [
{ "name": "priority" },
{ "name": "active" }
]
}
```
通常のパースでは `id`、`name`、`address`（オブジェクトのまま）、`tags`（配列のまま）の 4 フィールドしか取得できません。`address.city` や `tags[*].name` といったネストされた値を個別に取り出すには、後続の変換コンポーネントで追加処理が必要でした。
Extended JSON extraction を **true** に設定すると、これらのネストされたプロパティや配列の要素がスキーマセクションに展開表示され、チェックボックスで直接選択できるようになります。つまり、`address.city`、`address.zip`、`tags[*].name` などを Rest API Source の段階でフラットなフィールドとして取り出せるのです。
### Multiple output parsesによる複数のデータセットを抽出
REST API のレスポンスが複雑で、異なるパスのデータを別々のコンポーネントに渡したいケースもあります。たとえば、1回のAPIコールで注文データと注文明細データを同時に含むレスポンスが返される場合、注文データは注文テーブルへ、明細データは明細テーブルへとそれぞれ別の流れで処理したい、というシナリオです。
コンポーネント設定画面のレスポンスセクションで、**Extended JSON extraction** オプションを**true**に設定します。設定後、スキーマセクションにネスト構造が展開された状態でフィールドが表示されるので、必要なフィールドにチェックを入れてください。
Extended JSON extractionでは、**+ Add output parse** ボタンを使って複数の出力パースを追加できます。追加された各パースはそれぞれ独立したスキーマセクションを持ち、異なるエッジ名を付けることが可能です。これにより、1 つの API レスポンスから複数の視点でデータを抽出し、それぞれを異なる後続コンポーネント（変換やデスティネーション）に接続できます。
* Bagデータの抽出
* Mapデータの抽出
* 複合データの抽出
### Extended JSON extraction を使う場面
* レスポンスにネストされたオブジェクトや配列が含まれていて、その中のフィールドを個別に取り出したい場合
* ネスト構造の展開処理をソースコンポーネントの段階で完結させ、下流の変換処理をシンプルに保ちたい場合
* 1つのレスポンスから複数の出力パースを生成して、異なるデスティネーションに振り分けたい場合
* サンプルデータに現れないフィールドを Key の手動編集で明示的に定義したい場合
### Key の手動編集：スキーマに表示されないフィールドへの対応
Extended JSON extractionを有効にしても、API レスポンスのサンプルデータの状態によっては、一部のネストフィールドがスキーマのフィールド一覧に表示されないことがあります。これは、サンプルとして取得されたレコードにおいて、そのフィールドが空（null や空配列）だった場合に発生します。
たとえば、`tags` が配列フィールドであるにもかかわらず、最初のレコードの`tags`が空配列 `[]` だった場合、`tags[*].test_field` はフィールド一覧に自動で現れません。
このようなケースでは、**スキーマのKeyを手動で編集**して対応できます。スキーマセクションで該当フィールドのKey値を直接`tags[*].test_field`のように書き換えることで、パイプライン実行時にそのフィールドが利用可能なレコードからは値が取得され、利用できないレコードでは null が設定されます。
この手動編集機能は、レスポンスの構造は把握しているものの、サンプルデータに全パターンが含まれていない場合に非常に便利です。
## 制限事項
Rest API Source を使用する際に知っておくべき制限事項があります。
* \*\*$ 記号のエスケープ**：API コール内で `$`記号を使用する場合は、バックスラッシュ`\` でエスケープする必要があります（`\$`）。なお、ランタイムでは正常に実行されますが、API ソースコンポーネントのプレビューやフロー内のコンポーネントプレビューではエラーが発生します
* **BAG フィールドの展開制限**：1 つのパースあたり、展開（flatten）できる BAG フィールドは 1 つまでです。別の BAG フィールドも展開したい場合は、新しいパースを追加して対応してください
* Bagタイプデータの展開前
* Bagタイプデータの展開後
## まとめ
Rest API Source は、外部 API からのデータ取り込みを認証・リクエスト・ページネーション・パースまで一貫してローコードで構築できるコンポーネントです。
特に **Extended JSON extraction** 機能は、従来であれば後続の変換コンポーネントで行っていたネスト構造の展開処理をソースの段階で完結させることができ、パイプライン全体の設計をシンプルに保てます。Key の手動編集によるスキーマ定義や、Multiple output parses による複数出力の生成など、実務で頻繁に求められるシナリオにも柔軟に対応できます。
まずは対象 API の認証方式とレスポンス構造を確認し、Extended JSON extraction の有効化を検討してみてください。ネストが深い API レスポンスほど、この機能の恩恵を強く実感できるはずです。