Extended JSON extractionによるネスト構造の展開

Extended JSON extractionによるネスト構造の展開とは

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 レスポンスがあった場合を考えてみましょう。

{
  "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 レスポンスほど、この機能の恩恵を強く実感できるはずです。