パラメータの使用

パラメータはレポートに追加した後、レポート内の様々な場所で参照し、特定の要件を満たすことができます。以下の記述で、パラメータを使用した様々なシナリオとその実装方法について説明します。

動的なクエリ

レポートのデータソースとして使用されるWeb APIに対して、動的に変更できるパラメータを使用することができます。パラメータを渡す方法は数多くありますが、最も一般的な方法について説明します。

パスにパラメータを使用する

パラメータは APIエンドポイントのパス内に含むことができます。たとえば、https://demodata.mescius.jp/northwind/api/v1/Categories/{id}/Productsのエンドポイントには、{id}がパラメータとなっており、商品リストを取得するカテゴリを指定することができます。

https://demodata.mescius.jp/northwind/api/v1/Categories/1/Productsをリクエストすると、カテゴリID = 1（飲料）の商品リストが返されます。
https://demodata.mescius.jp/northwind/api/v1/Categories/2/Productsをリクエストすると、カテゴリID = 2（調味料）の商品リストが返されます。

次の手順は、ユーザーが商品カテゴリを選択できるレポートを作成する方法を示します。

レポートに、以下イメージに合わせて値を設定し、データソースを追加します。
続けて、以下イメージに合わせて値を設定し、データセットを追加します。作成したCategoriesデータセットは、全てのカテゴリのリストを取得します。
続けて、レポートパラメータを追加します。以下イメージ合わせて、CategoryIDパラメータを追加します。
Productsデータセットを追加します。Productsデータセットは、パラメータとしてCategoryIDパラメータを使用します。［検証］をクリックすると、フィールドリストを取得するためにパラメータ値の入力を求める［パラメータ値］ダイアログが表示されます。「1」を入力して、［保存して実行］をクリックします。
Tableコントロールを追加し、Productsデータセットから{productName}、{unitPrice}、{unitsInStock}、{unitsOnOrder}のフィールドをTableコントロールにドラッグ＆ドロップします。
レポートをプレビューすると、ユーザーにカテゴリを選択するように求めます。カテゴリを選択すると、カテゴリに関連する商品が表示されます。

クエリにパラメータを使用する

パラメータは、クエリに使用することも可能です。クエリはサーバにデータを送るためのURLの末尾に付け足す文字列です。クエリパラメータは、URLの末尾に書かれ、最初に「?」をつけます。ODataを利用するAPIは、これらのクエリパラメータを使用して特定のフィールドを並べ替え、フィルタ、展開、絞り込む、および選択する機能を提供します。

[https://demodata.mescius.jp/northwind/odata/v1/Products?$filter=CategoryId eq 1](https://demodata.mescius.jp/northwind/odata/v1/Products?$filter=CategoryId eq 1)は、カテゴリID = 1（飲料）の商品リストを返します。
[https://demodata.mescius.jp/northwind/odata/v1/Products?$filter=CategoryId eq 2](https://demodata.mescius.jp/northwind/odata/v1/Products?$filter=CategoryId eq 2)は、カテゴリID = 2（調味料）の商品リストを返します。

次の手順は、ユーザーが商品カテゴリを選択でき、選択したカテゴリに関連付けられた商品を表示するレポートを作成する方法を示します。

レポートに、以下イメージに合わせて値を設定し、データソースを追加します。
続けて、以下イメージに合わせて値を設定し、データセットを追加します。
続けて、レポートパラメータを追加します。以下イメージ合わせて、CategoryIDパラメータを追加します。
Productsデータセットを追加します。Productsデータセットは、CategoryIDパラメータを利用して、$filterクエリパラメータの値を決定します。［検証］ボタンをクリックすると、フィールドリストを生成するためにパラメータ値の入力を求めるダイアログが表示されます。「1」を入力して、［保存して実行］をクリックします。
Tableコントロールを追加し、Productsデータセットから{productName}、{unitPrice}、{unitsInStock}、{unitsOnOrder}のフィールドをTableコントロールにドラッグ＆ドロップします。
レポートをプレビューすると、ユーザーにカテゴリを選択するように求めます。カテゴリを選択すると、カテゴリに関連する商品が表示されます。

GraphQLクエリ

GraphQL APIを使用する場合、クエリ引数はPOSTリクエストの本文内で渡されます。次の手順は、ユーザーが商品カテゴリを選択できるレポートを作成する方法を示します。

レポートにデータソースを追加します。GraphQLクエリの要件として、HTTPヘッダのContent-Typeは application/jsonに設定されます。
Categoriesデータセットを追加します。メソッドはPOSTであり、POSTリクエスト本文でJSON形式が使用されます。
続けて、レポートパラメータにCategoryIDパラメータを追加します。
Productsデータセットを追加します。Productsデータセットは、CategoryIDパラメータを利用して、idパラメータをクエリに渡し、指定されたカテゴリのみを返します。［検証］ボタンをクリックすると、フィールドリストを生成するためにパラメータ値の入力を求めるダイアログが表示されます。「1」を入力して、［保存して実行］をクリックします。
Productsデータセットをレポートにドラッグ＆ドロップします。
レポートをプレビューすると、ユーザーにカテゴリを選択するように求めます。カテゴリを選択すると、カテゴリに関連する商品が表示されます。

HTTPヘッダ

動的なHTTPヘッダを使用する一般的なシナリオは、ユーザーの資格情報を使用してデータリクエストを承認することです。次の手順は、Bearer認証とHTTPのAuthorizationリクエストヘッダを使用して動的なHTTPヘッダを作成する方法を説明します。

次のように、レポートにパラメータを追加します。［非表示］フラグを「はい」に設定します。パラメータの値をアプリケーションのコードに割り当てるので、ユーザーからの対話型アクションが必要ないです。
データソースを追加します。パラメータの値を参照するAuthorizationリクエストヘッダを設定します。
Productsデータセットを追加します。任意のデータ領域（たとえば、Tableなど）を追加してデータセットからのデータを表示します。

アプリケーションではビューワコンポーネントを使用してレポート出力を表示する場合は、ユーザーのアクセストークンをAccessTokenパラメータの値として渡すようにパラメータ値を設定できます。

// これは、現在ログインしているユーザーのアクセストークンを取得する擬似コードです。
// T具体的な実装はアプリケーションのアーキテクチャによって異なります。
const accessToken = authService.getAccessToken(); 
// 取得したaccessTokenをレポートのパラメータ値として渡します。
viewer.open("Products.rdlx-json", {
    ReportParams: [
        {
            Name: "AccessToken",
            Value: [accessToken],
        },
    ],
});

アプリケーションがAPIを介してレポートをエクスポートする場合、次のようにパラメータの値を渡すことができます。

async function exportReport(reportUrl) {
  // これは、現在ログインしているユーザーのアクセストークンを取得する擬似コードです。
  // 具体的な実装はアプリケーションのアーキテクチャによって異なります。
  const accessToken = authService.getAccessToken();
  var reportDef = await fetch(reportUrl).then((response) =>
    response.json()
  );
  const report = new GC.ActiveReports.Core.PageReport();
  await report.load(reportDef, reportParameters: [{
        Name: 'AccessToken',
        Value: [accessToken]
    }]);
  const doc = await report.run();
  const result = await GC.ActiveReports.PdfExport.exportDocument(doc, {});
  result.download("access-token.pdf");        
}

ランタイムフィルタ

特定のシナリオでは、パラメータの値を変更すると新しいデータリクエストがトリガーされます。この手法では、サーバー側のフィルタリングによって取得されたデータの量が削減されるが、リクエストの送信と応答の処理に追加に時間がかかります。

シナリオによっては、すべてのデータを一度に受信して、新しいデータリクエストを送信せずにパラメータ値に基づいてクライアント側でフィルタを適用したい場合があります。これは、パラメータ値にバインドされたデータ領域のフィルタを使用することで実現できます。

次の手順は、このシナリオを実装する方法を示します。

レポートに、以下イメージに合わせて値を設定し、データソースを追加します。
続けて、以下イメージに合わせて値を設定し、データセットを追加します。
続けて、レポートパラメータを追加します。以下イメージ合わせて、CategoryIDパラメータを追加します。
Productsデータセットを追加します。Productsデータセットはすべての商品を取得します。取得されたるフィールドのリストは、OData APIの$selectクエリーオプションによって制限されます。
Productsデータセットをレポートにドラッグ＆ドロップします。これにより、ProductNameとCategoryIdの列を含む新しいテーブルが自動的に作成されます。
新しく作成したテーブルを選択し、［プロパティ］タブに移動します。データ > フィルタの順に選択して、［追加］をクリックします。
フィルタエディタで、［+ 追加］ボタンをクリックします。「=」記号の左側でドロップダウンリストからCategoryIdを選択し、「=」記号の右側にあるテキスト領域をクリックして、ドロップダウンリストからCategoryIDを選択します。
レポートをプレビューして、カテゴリを切り替えます。追加のデータリクエストがトリガーされないで、テーブルには選択したカテゴリの商品が表示されます。

対話的な機能によるパラメータの適用

ActiveReportsJSでは、［パラメータ］パネルを使用してパラメータ値を設定できるだけでなく、対話的な機能によっても設定できます。ユーザーがレポート内の対話型要素をクリックすると、Apply Parametersアクションがアクティブ化になり、より動的で応答性の高いレポート対話が可能になります。

この手法は、ダッシュボードのような機能を提供する対話型フィルタを構成する時に役に立ちます。ダッシュボードを使ったレポートを作成する方法については、「ダッシュボード」を参照してください。このチュートリアルでは、レポートで対話型アクションを使用してユーザーエクスペリエンスを向上させる方法について説明しています。

レポート間でのデータの受け渡し

ActiveReportsJSでは、SubReportコントロールを使用してあるレポートを他のレポート内に統合できます。この機能により、リンクされたレポートの出力をメインレポートに埋め込むことができます。この機能の例としては、マスター詳細レポートであり、メインレポートには一般的な概要（マスターデータ）が表示され、サブレポートには各レコードのより詳細なデータが表示されます。

このようなレポートを作成するには、リンクされたレポートに非表示のパラメータを含めることができます。これらのパラメータはメインレポートから値を受け取り、特定のデータをサブレポートに送信できます。これらの値の受け渡しは、SubReportコントロールのプロパティによって実行され、必要に応じてこれらのパラメータの値を設定できます。

パラメータ値はドリルスルーレポートにも渡されます。ドリルスルーレポートを使用すると、サブレポートの詳細データにドリルスルーして、メインレポートから追加の関連データを表示できます。

ドリルスルーレポートを作成する方法については、「ドリルスルーレポート」を参照してください。

レポート出力のカスタマイズ

レポートコントロールでは、実行時に式を使用できるプロパティが提供しています。これらの式にパラメータ値への参照を含めることができます。この機能を使用すると、ユーザーの設定に基づいてレポート出力を調整できます。

例えば、レポートにDarkおよびLightという2つの値を指定できるThemeパラメータがあるシナリオを考えてみます。このパラメータをレポートコントロールのプロパティで参照すると、テーマを動的に切り替えることができます。

例としては、テキストボックスのテキストの色を{IIF(@Theme="Dark", "White", "Black")}に設定し、背景色を{IIF(@Theme="Dark", "Black", "White")}に設定できます。この設定により、選択したテーマに基づいてテキストと背景色が調整され、よりパーソナライズされたユーザーエクスペリエンスが提供します。

複数値パラメータの操作

パラメータプロパティの［複数の値を許可する］属性は、パラメータに複数の値を含めることができるかどうかを指定するために使用されます。この属性が設定されている場合、パラメータの値は式内のArrayオブジェクトとして扱われます。この配列は別の形式に変換する必要があります。

たとえば、配列をカンマまたはその他の区切り文字で区切られた値の文字列に変換するには、{Join(@parameterName, ",")``<span style="color: rgb(110, 110, 120); font-family: 'JetBrains Mono', SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace; font-size: 13.6px; font-style: normal; font-variant-ligatures: none; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: pre-wrap; background-color: rgb(250, 250, 250); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial; display: inline !important; float: none;">}</span>形式のようにJoin関数を使用できます。

レポートでより複雑な操作が必要な場合は、カスタム関数を利用できます。カスタム関数を使用すると、配列を入力として受け取り、必要な出力を返す関数を作成できます。これにより、特定の要件に応じて複数値パラメータをより柔軟に処理および操作できます。

カスケード型パラメータの使用

カスケード型パラメータを使用すると、1つのパラメータから値を取得し、その値を別のパラメータに対して使用できます。たとえば、「固定レイアウトを使ったレポート」チュートリアルでは、この機能を使用して選択した顧客の注文リストを表示します。カスケード型パラメータは、次の要素から構成されます。

データセット：最初のパラメータの値に依存します。たとえば、「固定レイアウトを使ったレポート」チュートリアルでは、ODataの$filterクエリーオプションを使用してデータをフィルタするデータセットを使用します。
2番目のパラメータ：データセットから使用できる値を取得します。最初のパラメータの値が変更されると、データセットは更新し、2番目のパラメータの使用できる値を更新します。この動的な対話によって、より応答性が高く直感的なユーザーエクスペリエンスが可能になります。

カスケード型パラメータを使用する方法