ページネーションの制御

コレクションを返す GET は通常、複数のルートリソースを返します。pageSize パラメータを使用して、指定されたペイロードで返されるルートリソースの数を制限できます。パフォーマンスや解析で実用的なリソースよりも多くのリソースをクエリで返すことがある場合に役立ちます。数の制限には、以下の構文を使用します。

pageSize=n

n は、返されるリソースのペイロードごとの最大数です。例：

GET /activities?pageSize=20

各リソースタイプには、デフォルトの pageSize があります。クエリで pageSize が指定されない場合、この値が使用されます。pageSize は、デフォルトの pageSize より大きく指定したり小さく指定できます。

また、各リソースには最大 pageSize があり、最大数より大きな pageSize でクエリを実行できません。

例えば、あるユーザーに 125 件のアクティビティがあると仮定した場合、アクティビティリソースでデフォルトの pageSize 値は 25 になり、最大 pageSize 値は 100 になります。

• GET /activities は最初の 25 件のアクティビティを返します（デフォルトの pageSize 値を使用）。
• GET /activities?pageSize=10 は最初の 10 件のアクティビティを返します。
• GET /activities?pageSize=30 は最初の 30 件のアクティビティを返します。
• GET /activities?pagesize=120 では、pageSize の値がリソースの最大数を超えているので、エラーを返します。

リソースの pageSize 値は、デフォルトで defaultPageSize=25 と maxPageSize=100 になります。個々のリソースは、API の apiconfig.yaml ファイルでこれらの値を上書きできます（例えば、claim-1.0apiconfig.yaml では、ActivityPatterns リソースがデフォルト値を上書きし、defaultPageSize=100 および maxPageSize=500 を使用します）。

include パラメータで追加した関連リソースの pageSize クエリを使用することもできます。詳細については、包含リソースでのクエリパラメータの使用を参照してください。

応答ペイロードにコレクションが含まれている場合、コレクションの各要素がペイロードの data セクションに一覧表示されます。各要素には links セクションがあり、その要素に関連するエンドポイントが含まれます。リンクの 1 つに self リンクがあります。例：

{
    "attributes": {
        ...
        "id": "cc:32",
        ... },
        ...
    "links": {
        ...
        "self": {
            "href": "/common/v1/activities/cc:32",
            "methods": [
                "get",
                "patch"
            ]
        }
    }
}

self リンクの href プロパティは、その特定要素へのエンドポイントです。必要に応じて、このリンクを使用して、その要素に対して実行する呼び出しを作成します。

応答ペイロードに使用可能なリソースの全部ではなく一部が含まれる場合は必ず、ペイロードの末尾にコレクションレベルの links セクションも含まれます。これらのリンクは操作とエンドポイントになり、リソースの特定の「ページ」で実行できます。（以下の説明で、N はクエリの pageSize です）。

• first リンクは、最初の N 個の要素へのエンドポイントです。
  • これはすべてのコレクションに表示されます。
• prev リンクは、要素で現在のセットの前にある N 個の要素へのエンドポイントです。
  • これは、ペイロードでその要素よりも前に要素がある場合に表示されます。
• next リンクは、要素で現在のセットの後にある N 個の要素へのエンドポイントです。
  • これは、ペイロードでその要素よりも後に要素がある場合に表示されます。
• self リンクは、要素の現在のセットへのエンドポイントです。
  • これは必ず（要素にもコレクションにも）表示されます。

例えば、25 件のアクティビティが現在の所有者にアサインされているとします。応答ペイロードでは pageSize の値が 5 で、特定のペイロードにはアクティビティの 2 番目のセット（アクティビティ 6～10）が含まれます。このペイロードのコレクションレベルのリンクは以下のようになります。

"links": {
    "first": {
        "href": "/common/v1/activities?pageSize=5&fields=id",
        "methods": [
            "get"
        ]
    },
    "next": {
        "href": "/common/v1/activities?pageSize=5&fields=id&pageOffset=10",
        "methods": [
            "get"
        ]
    },
    "prev": {
        "href": "/common/v1/activities?pageSize=5&fields=id",
        "methods": [
            "get"
        ]
    },
    "self": {
        "href": "/common/v1/activities?pageSize=5&fields=id&pageOffset=5",
        "methods": [
            "get"
        ]
    }
}

特定のリソースで始まるコレクションにアクセスするために、システム API では pageOffset パラメータを使用します。このパラメータは、コレクションの prev リンクと next リンクで使用されます。pageOffset インデックスは 0 から始まるので、理論的には pageOffset=0 は 1 番目の要素から始まり、pageOffset=5 は最初の 5 つの要素をスキップして 6 番目から始まります。

正しい pageOffset 値でリンクを構築する方法の判断は、少し複雑になることがあります。Guidewire では、応答ペイロードで提供される prev と next を使用して、独自の pageOffset クエリの構築は避けることをお勧めします。

データのクエリの際、条件を満たすリソースの合計数を取得できます。この数を取得するには、以下の構文を使用します。

includeTotal=true

このクエリパラメータを送信すると、合計を指定する total 値がペイロードに追加で含まれます。例：

"total": 72

includeTotal クエリパラメータを使用すると、応答ペイロードには以下の 2 つの集計値が含まれます。

• count：このペイロードで返されるリソースの数
• total：クエリの条件を満たすリソースの合計数

条件を満たすリソースの合計数が pageSize 以下の場合、count と total の値は同じになります。条件を満たすリソースの合計数が pageSize より大きい場合、count は total よりも小さくなります。count は total より大きくなりません。

パフォーマンス上の理由により、Guidewire では最大 1,000 までの合計アイテム数のみをカウントします。total の値が 1,000 と等しい場合、実際のカウントは 1,000 と同等以上になることがあります。

状況によっては、特定の条件を満たすリソースの合計数のみを取得することに関心があり、特定リソースの情報は必要ない場合もあります。しかし、含まれる合計のみを GET で返すことはできません。条件を満たすリソースがある場合に返される内容は、最初の N 個のリソースセットと、各リソースの 1 つ以上のフィールドにする必要があります。Guidewire では、呼び出しの送信でリソースの合計数のみを取得する場合、GET ...?includeTotal=true&fields=id&pageSize=1 など、最少量のリソース情報を返すクエリパラメータによる呼び出しの使用をお勧めします。

include パラメータで追加した関連リソースには、includeTotal クエリも使用できます。詳細については、包含リソースでのクエリパラメータの使用を参照してください。

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