包含リソースでのクエリパラメータの使用

一部のエンドポイントでは、特定の種類のリソースや、その種類に関連するリソースタイプのクエリを行う機能をサポートしています。例えば、デフォルトで、GET /activities エンドポイントは、アクティビティリソースのみを返します。ただし、include クエリパラメータを使用して、返されるアクティビティに関する備考・経緯を応答ペイロードに含めることができます。これらの種類のリソースは、包含リソースと呼ばれます。包含リソースを GET に追加する手法は、応答包含または読み取り包含と呼ばれることがあります。

包含リソースを追加する構文は以下のとおりです。

?include=<resourceName>

例えば、GET /activities?include=notes は、現在の呼び出し元にアサインされているすべてのアクティビティと、そのアクティビティに関連付けられたすべての備考・経緯を返します。

include のデフォルト動作の詳細については、包含リソースが含まれる応答のペイロード構造を参照してください。

主要リソースで使用可能なほとんどのクエリパラメータは、包含リソースでも使用できます。

包含リソースに適用するクエリパラメータの指定

包含リソースのクエリ式の一般的なパターンは、式の値で包含リソース名を指定することです。例えば、現在のユーザーと関連の備考・経緯にアサインされたアクティビティをすべて、以下の呼び出しで取得します。返される備考・経緯の数は 5 つまでに制限されています。

GET /activities?include=notes&pageSize=notes:5

包含リソースと主要リソース

包含リソースのクエリ式は、主要リソースのクエリ式からは独立しています。主要リソースのみ、包含リソースのみ、または両方にクエリ式がある場合があります。例えば、以下の 3 つのクエリはすべて、アクティビティと関連の備考・経緯を返します。ただし、pageSize パラメータの影響が異なります。

  • GET /activities?pageSize=7&include=notes
    • 7 つまでのアクティビティに応答は制限されています。
    • 備考・経緯に制限はありません。
  • GET /activities?include=notes&pageSize=notes:5
    • アクティビティに制限はありません。
    • アクティビティごとに備考・経緯が 5 つまでに応答は制限されています。
  • GET /activities?pageSize=7&include=notes&pageSize=notes:5
    • 7 つまでのアクティビティに応答は制限されています。
    • アクティビティごとに備考・経緯が 5 つまでに応答は制限されています。

包含リソースとその他の包含リソース

各包含リソースのクエリ式も、その他の包含リソースのクエリ式から独立しています。特定の GET に複数の包含リソースが含まれる場合、すべての包含リソースに特定のクエリ式を適用するには、各包含リソースでクエリ式を指定する必要があります。

例えば、すべてのクレームの GET を行うとします。ただし、応答ペイロードには主要な連絡先と報告者のみを含めたいと望み、これらの連絡先の ID、主に使用する電話番号、および勤務先電話番号のみが必要と仮定します。この応答を取得するには、以下のように送信する必要があります。

GET /claims?include=mainContact,reporter
           &fields=mainContact,reporter
           &fields=mainContact:id,primaryPhone,workPhone
           &fields=reporter:id,primaryPhone,workPhone

この例では、返されるフィールドを、ID、主に使用する電話番号、および勤務先電話番号のみに制限するロジックを、各包含リソースに対して指定する必要があります。

包含リソースのクエリパラメータの概要

filter パラメータ

一定の条件を満たさない包含リソースをフィルタで除外できます。

  • 構文： filter=resource:field:op:value
  • 例：
    GET claim/v1/claims/demo_sample:1?
       include=activities&
       filter=activities:escalated:eq:true
  • 戻り値：クレーム demo_sample:1 とそれに含まれるエスカレート済みのアクティビティ

fields パラメータ

包含リソースで返すフィールドを指定できます。

  • 構文： fields=resource:field_list
  • 例： 
    GET claim/v1/claims/demo_sample:1?
          include=activities&
          fields=activities:id,dueDate
  • 戻り値：クレーム demo_sample:1 とそれに含まれるアクティビティ。そのアクティビティの id と dueDate のみが返される。

sort パラメータ

包含リソースの並べ替えができます。この並べ替えは、ペイロードの related セクションと included セクションの両方に反映されます。

  • 構文： sort=resource:properties_list
  • 例： 
    GET claim/v1/claims/demo_sample:1?
          include=activities&
          sort=activities:dueDate
  • 戻り値：クレーム demo_sample:1 とそれに含まれるアクティビティで、期日を基準に並べ替えられる。

pageSize パラメータ

ルートリソース 1 つあたりの包含リソースの最大数を指定できます。また、pageSize を包含リソースで使用する際は、包含リソースレベルの prev リンクと next リンクはありません。

  • 構文： pageSize=resource:n
  • 例： 
    GET claim/v1/claims/demo_sample:1?
          include=activities&
          pageSize=activities:5
  • 戻り値：クレーム demo_sample:1 と、それに含まれる最大 5 つのアクティビティ

includeTotal パラメータ

包含リソースの合計数を含めることができます。

  • 構文： includeTotal=resource:true
  • 例： 
    GET claim/v1/claims/demo_sample:1?
          include=activities&
          includeTotal=activities:true
  • 戻り値：クレーム demo_sample:1、それに含まれるアクティビティ、および demo_sample:1 に含まれるアクティビティの合計数

チュートリアル：包含リソースのクエリパラメータを含む GET の送信

このチュートリアルでは、Postman を使用する環境を設定し、適切なサンプルデータセットを用意していることを前提としています。詳細については、チュートリアル：Postman 環境のセットアップを参照してください。

チュートリアル手順

  1. Postman で、［Launchpad］タブの右側の［+］をクリックして、新しい要求を開始します。
    1. ［権限］タブで、ユーザー名 aapplegate とパスワード gw を使用して、［Basic Auth］を選択します。
  2. 以下のように入力して、［送信］をクリックします。

    GET http://localhost:8080/cc/rest/claim/v1/claims?include=activities

  3. 2 つ目の要求タブを開き、1 つ目のタブを右クリックして、［Duplicate Tab］を選択します。
  4. 以下のように入力して、［送信］をクリックします。

    GET http://localhost:8080/cc/rest/claim/v1/claims?fields=id,claimNumber&include=activities&filter=activities:escalated:eq:true

結果の確認

2 つのペイロードを比較します。以下の相違点に注目します。

1 つ目のペイロード：

  • クレームについては、デフォルトのクレームフィールドが返されます。
  • アクティビティについては、すべてのアクティビティが返されます。

2 つ目のペイロード：

  • クレームについては、id フィールドと claimNumber フィールドのみが返されます。
  • アクティビティについては、エスカレート済みのアクティビティのみが返されます。