データの連結

データの連結は、レポートと表示されるレポートのデータの間に接続を確立します。ActiveReportsJSは、設計時に簡単な接続構成を使用することで、さまざまなデータソースへのバインドをサポートしています。また、高度なユースケース向けの豊富なAPIを提供しています。このトピックでは、ActiveReportsJSでのデータの連結の基本的な概念といくつかの一般的なシナリオについて紹介します。

データソースの構成

ActiveReportsJSでデータをバインドするには、最初にデータソースを追加する必要があります。ActiveReportsJSはCSV形式およびJSON形式をサポートしています。データソースには、以下の2種類があります。

• 外部ファイルまたはURL ：設計時に、REST APIなどのようなデータエンドポイントにレポートをバインドできます。

• 埋め込み ：データをレポート内で保持できます。この方法は、プログラムでレポートにデータを提供する場合に役立ちます。

ActiveReportsJSデザイナアプリケーションを使用してデータソースをレポートに連結するには、次の手順を実行します。

1. ［データ］ タブを選択し、［データソース］ の右側のアイコン ［+追加］ をクリックします。

2. ［データソースの編集］ ダイアログでは、新しく追加されたデータソースの名前を指定します。

3. ［種類］ ドロップダウンリストから、データセットの形式に応じて、JSONまたはCSVを選択します。

4. ［形式］ を 「外部ファイルまたはURL」 または 「埋め込み」 に設定します。［埋め込み］ は、レポートに静的なデータを埋め込む場合に便利で、レポートのデザインがデータ構造およびコンテンツと確実に一致するようにします。

［外部ファイルまたはURL］データソースの構成

［外部ファイルまたはURL］データソースを設定するには、次のプロパティを指定できます。

• エンドポイント - 簡単なシナリオとは、データソースを直接指すURL、例えば、「https://demodata.mescius.jp/northwind/api/v1/Products」を指定します。このURLは、JSON形式で商品リストを取得します。高度なシナリオとは、データセットを使用してエンドポイントのパスが追加されるベースURLを指定します。例えば、エンドポイントを「https://demodata.mescius.jp/northwind/api/v1」に設定できます。これは、Northwind REST APIの /Products, /Categoriesおよびその他のエンドポイントのベースURLです。データセット内で接続プロパティを定義する場合、エンドポイントを空白のままにすることもできます。

• HTTP ヘッダ - 要求に沿って渡されるHTTPヘッダフィールドのコレクションです。フィールドの値は実行時に評価される式に設定できます。例えば、承認フィールドを現在のユーザーに基づいてアプリケーションのコードが実行されるレポートパラメータ値に設定できます。動的にパラメータ値の設定の詳細については、「パラメータの使用」を参照してください。

• クエリパラメータ - URLのクエリ文字列を定義する（パラメータ、値）ペアへのコレクションです。各パラメータの値は、実行時に評価される式に設定できます。例えば、クエリパラメータをレポートパラメータの値に設定して、実行時にデータをフィルタできます。

次の画像は、「Northwind ProductsOData」エンドポイントの完全な構成の例を示します。

［埋め込み］データソースの構成

埋め込むデータソースは、レポート内に直接組み込まれます。実行時にデータを提供する場合も、設計時にプレースホルダーデータを指定する必要があります。このダミーデータにより、実際のデータセットで予期される構造とフィールド名を識別できます。

例えば、Northwind製品リストをレポートに埋め込むには、Northwindデータの構造を真似るプレースホルダーデータを使用して、設計時にデータソースを構成します。これは、サンプルファイルを選択するか、データを手動で入力することによって実行できます。

ダミーデータは、ファイルからロードするか、また手動で入力できます。

データセットの構成

各データソースには、1つ以上のデータセットが含まれている可能性があります。 ［データソース］ ダイアログで変更を保存して、 ［データ］ タブでデータソース名の横にある `+`アイコンをクリックし、データセットを追加します。

データセットの基本的な構成設定

JSONとCSVの両方のデータセットを構成する時、次のプロパティを指定できます。

• Uri/パス - 値は親データソースの構成によって異なります。

  • データソースのエンドポイントが完全なURL（例、https://demodata.mescius.jp/northwind/api/v1/Products）である場合、データセットの「Uri/パス」は空にします。

  • データソースのエンドポイントがベースURL（例、https://demodata.mescius.jp/northwind/api/v1）である場合、データセットのUri/パスには/Productsや/Categoriesなどのエンドポイントパスを指定します。

  • データソースのエンドポイントが空の場合、データセットのUri/パスにはデータエンドポイントの完全なURLを指定します。

  • データソースのタイプがEmbedded JSONの場合、データセットのUri/パスは空にします。

• メソッド - リクエストメソッドを指定します。サポートされているメソッドは、GETと POSTです。 Remote JSONデータソースタイプにのみ適用されます。

• Post内容 - POSTリクエストの本文を指定します。このプロパティを使用して、データセットをGraphQLエンドポイントに接続できます。Post内容は実行時に評価される式に設定できます。

• パラメータ および ヘッダ - これらのプロパティの目的は、データソースのクエリパラメータおよびHTTPヘッダプロパティと同じです。親データソースのエンドポイントがベースURLまたは空の値である場合、データセットでパラメータとヘッダを設定できます。本プロパティはRemote JSONデータソースタイプにのみ適用されます。

[
    {
        "productId": 1,
        "productName": "果汁100% オレンジ",
        ... 残りのプロパティ
    },
    {
        "productId": 2,
        "productName": "果汁100% グレープ",
    },
    ... 残りのデータ
]

JSONデータセットの構成

JSONのデータ構造は、本質的に階層的であり、任意で複雑にできます。JSONデータセットを構成する場合、JSONパスプロパティが必要です。このプロパティは、JSONPath式を使用して、対象のデータへのルートオブジェクトを指定します。JSONPath式は、JSON構造を解析するための強力な式で、データ内で繰り返される要素を特定する場合に役立ちます。

例えば、次のようにNorwthind Products Dataエンドポイントは、Productオブジェクトの配列を返します。

[
    {
        "productId": 1,
        "productName": "果汁100% オレンジ",
        ... 残りのプロパティ
    },
    {
        "productId": 2,
        "productName": "果汁100% グレープ",
    },
    ... 残りのデータ
]

JSONパスには$.* または $[*]の式を使用して、繰り返される製品エントリを指定できます。これらの式は、配列内の各項目を効果的に反復します。

ODataエンドポイントによって返される同じ製品リストは少し異なります。

{
    "@odata.context": "https://demodata.mescius.jp/northwind/odata/v1/$metadata#Products",
    "value": [
        {
            "ProductId": 1,
            "ProductName": "果汁100% オレンジ",
            ... 残りのプロパティ
        },
        {
            "ProductId": 2,
            "ProductName": "果汁100% グレープ",
        },
        ... 残りのデータ
    ]
}

この場合は、JSONパスに$.value.* または $.value[*]の式を使用して、valueキー内の製品の配列にアクセスします。

JSONパスにはリッチな構文があるので、公式ページを参照して他の例を確認できます。

CSVデータセットの構成

CSVデータセットを構成するには、次のプロパティを使用できます。

• 先頭行をヘッダとする：CSVファイルの先頭行をヘッダとして使用するかどうかを決定します。

• 開始行：データ取得の開始位置を指定します。

• 区切り文字：列を区切るためのシンボルです。カンマ、セミコロン、タブ、スペースのいずれかを選択します。

• 重ねて表記でエスケープ（区切り文字）：区切り文字を連続して表記した場合に、１つの文字として扱うかどうかを決定します。

• 改行コード：改行書式の記号です。CRLF（キャリッジリターンとラインフィード）、CR（キャリッジリターン）、LF（ラインフィード）から選択可能です。

• 重ねて表記でエスケープ（改行コード）：改行コードを連続して表記した場合に、１つの文字として扱うかどうかを決定します。

データセットの検証

上記のプロパティを設定したら、データセットを検証し、フィールドリストを取得できます。 ［新規データセット］ ダイアログでは、この両方の操作を実行するために検証ボタンをクリックします。

構成が無効な場合、またはデータ接続に問題がある場合、ダイアログの上部にエラーメッセージが表示されます。

データセットは正しく構成された場合、データフィールドのリストが表示されます。データフィールドのリストを展開するには、データベースフィールドセクションの表示アイコンをクリックします。

データセットのフィールド

データセットのフィールドは、データベースフィールドと計算フィールドで構成されています。データベースフィールドはデータ自体から作成され、 計算フィールドは、レポートの作成者が記述できます。

データベースフィールドを使用する場合、次の操作を実行できます。

• フィールド名を変更する：レポートで使用するデフォルトのフィールド名を置き換えます。データフィールドの名前が長すぎる場合や、特殊文字が含まれる場合に役に立ちます。

• データタイプと形式に注釈を付ける：各データフィールドに、対応するデータタイプと形式で注釈を付ける必要があります。この機能は、CSVデータセットで数値、日付、ブール値などのフィールドを指定する重要です。また、JSONデータセットでは、日付は通常文字列で表されるため、日付フィールドを指定する時よく使用されます。

• 計算フィールドを追加する

データタイプに注釈を付ける

データ注釈は、FieldName[Type|Format]という構文を使用してフォーマットされます。Typeは次のいずれかになります。

• Number：数値の場合

• Date：日付の場合

• Boolean：true／false値の場合

• String：テキストの場合（デフォルト）

Formatはタイプ固有であり、データの種類と一致する必要があります。

以下の表は、注釈内のDate形式を定義するトークンを示しています。

たとえば、データセットで10/31/2023の形式で表示される日付フィールドに注釈を付ける場合、正しい注釈はOrderDate[Date|MM/DD/YYYY]になります。

計算フィールドを追加する

計算フィールドは、1つ以上の既存のデータベースフィールドに対して操作を実行することによって作成されます。計算フィールドは、次のようなさまざまな操作を実行します。

• 算術演算（合計、平均、複雑な数式など）

• 文字列操作（テキストの結合や文字列形式の変更など）

• 論理演算（条件ベースの値またはブール論理など）

計算フィールドを追加するには、「計算フィールド」 セクションの右側にある 「+」 アイコンをクリックします。 レポートで使用する 「フィールド名」 を設定し、値を式に設定します。

例えば、データベースフィールドリストに OrderLineエンティティのUnitPrice、 Quantity、およびDiscountPerUnitフィールドが含まれている場合、TotalPriceという計算フィールドを追加して、その値を以下のように設定できます。

{(UnitPrice - DiscountPerUnit) *  Quantity}

計算フィールドの値は、元のデータセットの各エンティティで自動的に使用可能になります。

データセットのフィルタ

OData APIの$filter操作などのようなデータソースの機能を使用してレポートに表示されるデータをフィルタリングすることをお勧めします。これにより、アプリケーションとデータソースの間にトラフィックが減少され、ActiveReportsJS側でのデータ処理が簡素化されます。

ただし、上記のデータセットの検証が正常に終了した後、データセットでフィルタを設定できます。フィルタセクションの右側にある + アイコンをクリックします。 フィルタするために使用するフィールドを式として設定します（例：=Fields!UnitPrice.Value）。 次に、Operatorをサポートされているフィルタ演算子（例：>）に設定します。最後に、フィルタの値（例： 1000）を設定します。この設定により、レポートには「UnitPrice > 1000」のデータエンティティのみが表示されます。

ネストされたデータセット

JSONデータは、エンティティ間に一対多のリレーションシップをあらわします。 例えば、OData Northwindエンドポイントへの次のリクエストは、各カテゴリに製品のリストが含まれているカテゴリのリストを返します。

GET https://demodata.mescius.jp/northwind/odata/v1/Categories?$expand=Products

ActiveReportsJSは、データでそのような構造を見つける場合、表示されるデータセットダイアログでデータセット階層が自動的に作成されます。

ネストされたデータ領域を使用してマスター詳細レポートがそのような構造を示す方法については、チュトリーアル、またはをデモを参照してください。

実行時のデータ連結

もし設計時にデータ接続を設定できない場合、実行時にレポートのアプリケーションコードにデータを追加できます。この場合は、上記に説明した「EmbeddedJSON」データソースタイプが使用できます。次の例は、Northwind Productsエンドポイントからデータを取得して、データソースプロパティに渡す方法について説明します。

// Fetch APIを使用して、リクエストを設定しますhttps://developer.mozilla.org/ja/docs/Web/API/Fetch_API
const headers = new Headers();
const dataRequest = new Request(
   "https://demodata.mescius.jp/northwind/api/v1/Products",
   {
      headers: headers
   }
);

// データを取得します
const response = await fetch(dataRequest);
const data = await response.json();

// レポート定義「jsonファイル」を取得します
const reportResponse = await fetch("Products.rdlx-json");
const report = await reportResponse.json();

// レポートにデータを追加します
report.DataSources[0].ConnectionProperties.ConnectString = "jsondata=" + JSON.stringify(data);

上記を処理の後は、レポートをビューワにロードするか、サポートされている形式にエクスポートできます。

コードサンプルについては、デモ を参照します。

関連リンク

• REST API

• GraphQL

• OData

• 実行時データ連結

• デモデータ

• ActiveReportsJSビューワについて

• チュートリアル3: マスター - 詳細レポートの作成