一覧取得¶
GET /api/v1/snapshots/list
概要¶
現在の Key から参照可能なページスナップショットをページングして読み取ります。
呼び出し前の準備と使用手順¶
現在の Key には routine.defaultAccess が必要です。現在の Key のワークスペースのみを対象とし、公開 API はクロススペース、filterType、needPaging、並べ替えパラメータを受け付けません。isHidden=0 で未削除、かつ isPublic=1 またはプライベート作成者が現在の Key の主体と等しいスナップショットのみを一覧表示します。現在の Key の作成者が現在の呼び出し主体でない場合、そのプライベートスナップショットは自動的に継承されません。id の降順で並べ、デフォルトは pageSize=100 です。例の 10 はデフォルトではありません。
content は data/declaration/workspaceVersionType オブジェクトを保持し、pageInfo はレスポンスのトップレベルにあります。type=RumHeatMap の場合は RUM ステータス/jsonContent を付加します。その他の type では dashboardIsPublic が付加される場合があります。表示用の概要は追加のアクセス認可ではなく、過去に削除されたアプリでも概要が残る場合があります。読み取りでは設定と保存された範囲のみを返し、スナップショット内のクエリは実行せず、共有設定/共有コードも返しません。旧ルール形式は、後続のすべての namespace が照会可能であることを意味せず、共有アクセス時に再生成を求められる場合があります。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| pageIndex | integer | 任意、1 以上、デフォルト 1。クライアントは整数文字列を使用します。 null 許可: False $minValue: 1 例: 1取得または入力方法: トップレベルの pageInfo に従ってページングします。 |
|
| pageSize | integer | 任意、1~100、デフォルト 100。古い例の 10 をデフォルトとして扱わないでください。 null 許可: False $maxValue: 100 $minValue: 1 例: 100取得または入力方法: 読み取り量に応じてページサイズを制御します。 |
|
| search | string | 任意。前後の空白を除去した SQL LIKE のあいまい一致で、%/_ はワイルドカードの意味を保持します。 null 許可: False 例: 支付取得または入力方法: 呼び出し元が名前で検索します。 |
|
| type | string | 任意の完全一致フィルタ文字列。前後の空白を除去し、省略または空の場合はフィルタしません。統一された公開列挙はありません。 null 許可: False 例: Log取得または入力方法: 対応するページまたは既存スナップショットの type から取得します(例: Log/RumHeatMap)。 |
パラメータ補足説明¶
スナップショットはページ設定とサーバー側のクエリ範囲を保存します。インターネット共有には別途共有設定の作成が必要で、snap_、share_、初回リダイレクト code、2 段目 token はそれぞれ異なる識別子です。
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/snapshots/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode type=Log \
--data-urlencode pageIndex=1 \
--data-urlencode pageSize=100
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | ページングされたコンテンツオブジェクト。 |
| content.data | array<object> |
このページで表示可能なスナップショット。一致しない場合は []。 |
| content.data[].id | integer または null | データベースの行 ID。パス特定には使用しません。送信前のスナップショットでは null になる場合があります。 |
| content.data[].uuid | string | スナップショット UUID。snap_ プレフィックス付き。 |
| content.data[].status | integer | リソースステータス。通常は 0 で、論理削除の 3 はクエリから除外されます。 |
| content.data[].creator | string | 最初に作成した主体の UUID。強制上書きでは creator が必ずしも変更されず、現在の権限保有者は accountUUID を参照します。 |
| content.data[].updator | string | 直近で上書き/削除更新した主体。 |
| content.data[].createAt | number | Unix 秒の作成/再生成時刻。強制上書きでは time.time() を使用するため、レスポンスで小数を含む場合があります。 |
| content.data[].updateAt | integer | Unix 秒の更新時刻。未更新の場合は -1 になることがあります。 |
| content.data[].deleteAt | integer | Unix 秒の削除時刻。未削除の場合は通常 -1 です。 |
| content.data[].workspaceUUID | string | 現在の Key が属するワークスペース。 |
| content.data[].name | string | スナップショット名。同じワークスペース内の同じ type で一意に特定されます。 |
| content.data[].type | string | ページスナップショットの種類(Log など)。保存側では公開列挙による検証は行いません。 |
| content.data[].filterType | string | 保存されたフィルタ分類。作成時に省略した場合は空です。強制上書きで同名の場合は、このフィールドを更新しません。 |
| content.data[].isPublic | integer | 1 はワークスペース内での公開表示、0 はプライベートです。インターネット上の公開共有ではありません。この公開スナップショットの作成では固定でデフォルト 1 となり、isPublic パラメータを受け付けません。 |
| content.data[].isHidden | integer | 非表示フラグ。0 の場合はこの一覧に表示され、非表示のレポートスナップショットは一覧に表示されません。 |
| content.data[].accountUUID | string | 生成時/最近の強制上書き時に権限を収集した主体の UUID。creator と異なる場合があります。 |
| content.data[].content | object | 保存されたページ/クエリ設定。実際のテレメトリデータのコピーではありません。動的フィールドは対応するページのプロトコルに従って解釈します。 |
| content.data[].content.routeName | string | コンソールのルート識別子(例: ログエクスプローラーの Log、ヒートマップの RumHeatMap)。トップレベルの type と互換性を保ちます。 |
| content.data[].content.routeParams | object | 対応するページのパスパラメータオブジェクト。 |
| content.data[].content.routeParams.source | string | ログエクスプローラーでは通常 all を使用します。具体的には遷移元ページによって決まります。 |
| content.data[].content.routeParams.其他键 | JSON | ページパスの動的パラメータ。現在のコンソールページで生成された設定に従います。 |
| content.data[].content.routeQuery | object | 対応するページの Query 状態。オブジェクトである必要があります。任意のクライアントクエリ値によって、サーバー側で取得済みの認可が拡大されることはありません。 |
| content.data[].content.routeQuery.w | string | ページのワークスペース識別子。通常は現在のワークスペースです。これによって API Key のスコープを変更することはできません。 |
| content.data[].content.routeQuery.workspaceUUID | string | ページで必要なクエリ対象ワークスペースのリスト(カンマ区切り)。実際のクロススペース認可とスナップショットの保存範囲による制限を引き続き受けます。 |
| content.data[].content.routeQuery.time | string | ページの時間範囲(例: 15m、または開始ミリ秒,終了ミリ秒の文字列)。相対時間は物理的に凍結されたデータではありません。 |
| content.data[].content.routeQuery.query | string | ページの検索クエリ文字列(ログエクスプローラーの例: service:payment)。スナップショット API が実行する DQL ではありません。 |
| content.data[].content.routeQuery.cols | string | 表示フィールド名のカンマ区切り(例: time,message,service)。 |
| content.data[].content.routeQuery.viewType | string | ログエクスプローラーでは通常 view(リスト)/analyze(分析)です。現在のページの実際のプロトコルに従います。 |
| content.data[].content.routeQuery.index | string | ログインデックス名のカンマ区切り。ログインデックス設定から取得します。読み取り権限は変更しません。 |
| content.data[].content.routeQuery.snapshotName | string | ページに表示されるスナップショット名。トップレベルの name と一致させることを推奨します。 |
| content.data[].content.routeQuery.dashboard_id | string | ダッシュボードスナップショットに対応する dsbd_ UUID。可視性の概要に使用します。先に現在のワークスペースで認可されたリソースを確認してください。 |
| content.data[].content.routeQuery.app_id | string | RUM ヒートマップの公開 appId。アプリの概要を付加するために使用します。 |
| content.data[].content.routeQuery.status | integer | 一覧の type=RumHeatMap の場合に、現在の RUM 設定ステータスが付加されることがあります。過去に削除されたものも表示される場合があります。 |
| content.data[].content.routeQuery.jsonContent | object | RUM ヒートマップの一覧でのみ付加される可能性がある、アプリの jsonContent。 |
| content.data[].content.routeQuery.jsonContent.name | string | アプリ名。 |
| content.data[].content.routeQuery.jsonContent.type | string | アプリのプラットフォームタイプ。 |
| content.data[].content.routeQuery.jsonContent.extend | object | 任意のアプリ拡張。 |
| content.data[].content.routeQuery.jsonContent.extend.自定义键 | JSON | アプリが保存した拡張値。 |
| content.data[].content.routeQuery.其他键 | JSON | ページのフィルタ/レイアウトなどの動的状態。バックエンドは主に保存するだけで、レンダリング可能かどうかの検証は行いません。 |
| content.data[].content.其他键 | JSON | 対応するページのその他の保存状態。クライアントがサーバー権限を注入できることを意味しません。 |
| content.data[].rules | object または null | サーバー側で収集されたクエリ権限/マスキングのスナップショット。読み取り専用です。クライアントは権限を得るために rules を送信したり、content 内で偽造したりしてはなりません。履歴形式は異なる場合があります。 |
| content.data[].rules.eventScopeVersion | integer | 新しい認可イベント範囲のバージョン 1。古いスナップショットにはこのキーがない場合があり、特定のクエリでは再生成が要求されます。 |
| content.data[].rules.ruleContextVersion | integer | 新しい形式は 2、古い形式は 1 または未指定の場合があります。 |
| content.data[].rules.roles | array<string> |
保存時に実際に呼び出した身元のロール識別子。書き込み可能なロール選択ではありません。 |
| content.data[].rules.roles[] | string | サーバーが確認した単一のロール ID。 |
| content.data[].rules.deniedNamespaces | array<string> |
クエリ禁止範囲(例: logging/rum/tracing/metric/lineage/keyevent)。実際にはサイトで認識されている namespace に依存します。 |
| content.data[].rules.deniedNamespaces[] | string | 単一の禁止データ範囲。 |
| content.data[].rules.rules | object | namespace → 取得済みデータアクセスルールの配列。 |
| content.data[].rules.rules.命名空间 | array<object> |
その範囲のルール。空配列はクエリ権限の代わりにはなりません。 |
| content.data[].rules.rules.命名空间[].rule_uuid | string | 元のアクセスルール UUID。 |
| content.data[].rules.rules.命名空间[].region_code | string | ルールが存在するサイト識別子。 |
| content.data[].rules.rules.命名空间[].rule_info | object | アクセス条件の内容。データ範囲に従って解釈します。 |
| content.data[].rules.rules.命名空间[].rule_info.sources | array<string> |
lineage/keyevent などの範囲で許可されるソース。元のルールプロトコルに従います。 |
| content.data[].rules.rules.命名空间[].rule_info.sources[] | string | 元のルールの単一ソース。クライアントによる新規認可ではありません。 |
| content.data[].rules.rules.命名空间[].rule_info.rule | string | 元のルールのフィルタ式。 |
| content.data[].rules.rules.命名空间[].rule_info.其他键 | JSON | その範囲の元データルールのその他のフィールド。 |
| content.data[].rules.rules.命名空间[].rule_mask_info | object | 元のデータアクセスルールに付随する任意のマスキング情報。 |
| content.data[].rules.rules.命名空间[].rule_mask_info.maskFields | string | カンマ区切りのフィールド。 |
| content.data[].rules.rules.命名空间[].rule_mask_info.reExprs | array<object> |
正規表現設定。 |
| content.data[].rules.rules.命名空间[].rule_mask_info.reExprs[].reExpr | string | マスキング正規表現。 |
| content.data[].rules.rules.命名空间[].其他键 | JSON | 元のアクセスルールの予約フィールド。この API で新たに実行されるパラメータではありません。 |
| content.data[].rules.sensitiveDataMaskRules | object | namespace → 機密フィールドルールの配列(履歴上の空オブジェクトと互換)。 |
| content.data[].rules.sensitiveDataMaskRules.命名空间 | array または object | 新しい形式で非空の場合はルールオブジェクトの配列である必要があります。空オブジェクトはルールなしとの互換です。 |
| content.data[].rules.sensitiveDataMaskRules.命名空间[].fields | array<string> |
元の機密フィールドリスト。 |
| content.data[].rules.sensitiveDataMaskRules.命名空间[].fields[] | string | フィールド名。 |
| content.data[].rules.sensitiveDataMaskRules.命名空间[].reExpr | string または null | 元の機密データマスキング正規表現。 |
| content.data[].rules.sensitiveDataMaskRules.命名空间[].其他键 | JSON | 元のルールのその他のフィールド。 |
| content.data[].dashboardIsPublic | integer または boolean | 関連ダッシュボードの可視性ヒント(任意)。関連ダッシュボードが存在する場合にのみ付加されることがあります。スナップショットの共有権限とは異なります。 |
| content.workspaceVersionType | string | 現在のワークスペースの製品バージョンタイプ。実際のデプロイ値であり、このフィールドによって共有機能が自動的に付与されることはありません。 |
| pageInfo | object | ページングのメタ情報。OpenAPI ではトップレベルにあり、content はオブジェクトを保持します。 |
| pageInfo.count | integer | このページの実際の件数。 |
| pageInfo.totalCount | integer | 現在の可視性とフィルタ条件を満たすスナップショットの総数。共有設定やテレメトリレコードの件数ではありません。 |
| pageInfo.pageIndex | integer | ページ番号。1 から始まります。 |
| pageInfo.pageSize | integer | 今回の 1 ページあたりのリクエスト件数。 |
| content.declaration | object または null | 現在のワークスペースの共通宣言。content の親オブジェクトにのみ追加され、data 項目へ再帰的には追加されません。 |
{
"code": 200,
"content": {
"data": [
{
"id": 7,
"uuid": "snap_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"workspaceUUID": "wksp_example",
"name": "支付服务日志",
"type": "Log",
"filterType": "",
"isPublic": 1,
"isHidden": 0,
"accountUUID": "wsak_example",
"content": {
"routeName": "Log",
"routeParams": {
"source": "all"
},
"routeQuery": {
"w": "wksp_example",
"time": "1785423600000,1785427200000",
"query": "service:payment",
"cols": "time,message,service",
"viewType": "view",
"index": "default",
"snapshotName": "支付服务日志"
}
},
"rules": {
"eventScopeVersion": 1,
"ruleContextVersion": 2,
"roles": [
"wsAdmin"
],
"rules": {},
"sensitiveDataMaskRules": {},
"deniedNamespaces": []
}
}
],
"workspaceVersionType": "pay",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE",
"pageInfo": {
"count": 1,
"totalCount": 1,
"pageIndex": 1,
"pageSize": 100
}
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては、共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 宣言されていない Query パラメータを使用した場合、またはパラメータがルールに違反した場合 | パラメータ解析失敗 | Query パラメータ表と例を確認してください。 |
| 500 | ft.InternalServerError | データベース/現在のワークスペース状態、履歴スナップショットの content 形状、ページング変換などの未処理例外 | 内部エラー | Query/履歴ページ設定を確認し、traceId を保持してバックオフしてください。保存されたすべてのオブジェクトが現在のフロントエンドバージョンでレンダリングできるわけではありません。 |