Instana REST API のページネーション

オンライン編集

Instana REST API では、Instana の API エンドポイントから返される大量のデータを効率的にナビゲートするために、ページネーションが使用されています。 このガイドでは、ページネーションの仕組みと効果的な使い方について説明します。

ページネーションを理解する

オンライン編集

APIエンドポイントが膨大なリソースのリストを返す場合、APIはページネーションを使用して、結果をより管理しやすいサイズのチャンクに分割する。 ページネーションのパラメータは、各APIレスポンスで返されるデータのサブセットを制御する。 ページベースとカーソルベースは、Instanaで使用される2種類のページネーションです。

ページベースのページネーション

オンライン編集

ページベースのページネーションでは、各APIリクエストで返されるデータのサブセットを制御するために、 page （ limit または offset と呼ばれることもあります）と pageSize パラメータが一般的に使用されます。

データ・モデル

オンライン編集

Instanaのページベースのページネーションタイプ Pagination 、次のようなデータモデルがあります：

{
    "type": "object",
    "properties": {
        "page": {
            "type": "integer",
            "format": "int32",
            "minimum": 1
        },
        "pageSize": {
            "type": "integer",
            "format": "int32",
            "maximum": 200,
            "minimum": 1
        }
    }
}

属性表

オンライン編集

次の表は、 Pagination タイプの属性の定義の概要である：

属性 説明
page 返された結果が表示される、データセット内の特定のページ。
pageSize 返されるデータの各ページまたはチャンクのサイズ。

ページネーションの例

オンライン編集

次の例は、 Pagination の使い方を示している：

{
    "page": 2,
    "pageSize": 50
}

どこで使えるのか？

オンライン編集

以下のAPIエンドポイント群は、 Pagination スキーマを使用している：

APIエンドポイントのセットであるアプリケーション・リソースは、ページベースのページネーションも提供する。 アプリケーションリソースは Pagination スキーマを使用しないが、代わりにリクエストペイロードスキーマに page と pageSize 属性を含む。

カーソルによるページネーション

オンライン編集

カーソルベースのページネーションでは、カーソルはデータを取得するデータセット内の位置を指す。 Instanaには、カーソルベースのページネーションの2つのサブタイプがあります。汎用のカーソルページネーション(CursorPagination)と、インフラストラクチャ監視に特化したカーソルページネーション(CursorPaginationInfraExploreCursor)です。

汎用カーソルによるページネーション

オンライン編集

CursorPagination タイプは、Instana の API で最も一般的なカーソルベースのページ分割です。

データ・モデル

オンライン編集

Instanaの汎用のカーソルベースのページネーション・タイプ、 CursorPagination は、以下のデータモデルを持っています：

{
    "type": "object",
    "properties": {
        "ingestionTime": {
            "type": "integer",
            "format": "int64"
        },
        "offset": {
            "type": "integer",
            "format": "int32"
        },
        "retrievalSize": {
            "type": "integer",
            "format": "int32",
            "maximum": 200,
            "minimum": 1
        }
    }
}

属性表

オンライン編集

次の表は、 CursorPagination タイプの属性の定義の概要である：

属性 説明
ingestionTime 連続するクエリ間で使用する開始点へのポインタ。
offset 連続するクエリ間で使用する開始点へのポインタ。
retrievalSize 取得する値の数。

カーソルベースのページネーションの例

オンライン編集

次の例は、 CursorPagination の使い方を示している：

{
    "ingestionTime": 1720104883,
    "offset": 2,
    "retrievalSize": 45
}

インフラモニタリングのためのカーソルによるページネーション

オンライン編集

このページネーション・タイプは CursorPaginationInfraExploreCursor と名付けられ、 cursor と retrievalSize の両方を持つ。 CursorPaginationInfraExploreCursor は、エンドポイントの Infrastructure Analyze グループでのみ使用されます。

データ・モデル

オンライン編集

Infrastructure Analyzeで使用されるカーソルベースのページネーションタイプ CursorPaginationInfraExploreCursor 、以下のデータモデルを持つ：

{
    "type": "object",
    "properties": {
        "cursor": {
            "$ref": "#/components/schemas/InfraExploreCursor"
        },
        "retrievalSize": {
            "type": "integer",
            "format": "int32",
            "description": "number of values to return"
        }
    }
}

カーソルベースのページネーションの InfraExplorerCursor プロパティは、それ自体がオブジェクトであり、以下のデータモデルを持っています：

{
    "type": "object",
    "description": "cursor to use between successive queries"
}

属性表

オンライン編集

次の表は、 CursorPaginationInfraExploreCursor タイプの属性の定義の概要である：

属性 説明
cursor 連続するクエリ間で使用する開始点へのポインタ。
retrievalSize 取得する値の数。 
{
    "type": "object",
    "properties": {
        "cursor": {
            "$ref": "#/components/schemas/InfraExploreCursor"
        },
        "retrievalSize": {
            "type": "integer",
            "format": "int32",
            "description": "number of values to return"
        }
    }
}