作成¶
POST /api/v1/snapshots/create
概要¶
ページスナップショットを保存するか、同名スナップショットを強制的に再構築します。
呼び出し前の確認と使用手順¶
現在の Key には snapshot.create 権限が必要です。保存されるのはページとクエリの設定であり、すべてのテレメトリを物理的にコピーするものではありません。データ保持期間、クエリサービス、保存された認可範囲は、後続の閲覧に引き続き影響します。作成時はデフォルトでワークスペース内公開の isPublic=1 になります(インターネット共有ではありません)。公開時は isPublic/isHidden/accountUUID/rules を受け付けません。
同一ワークスペース、同一 type、同一 name に有効なレコードが存在する場合、isForce=false では重複名エラーを返します。true の場合は同一 UUID 上でオブジェクト全体の content を上書きし、現在の呼び出し Key からクエリ/マスキング認可を再収集して accountUUID と生成時刻を変更します。元の作成者が持つより大きな権限は引き継ぎません。元の filterType は強制上書きによって更新されず、元の creator が引き続きプリンシパルとなる場合があります。
このスナップショットを指す既存の共有は、後続のクエリで更新後のサーバー側範囲を読み取ります。強制再構築により共有のクエリ可能範囲が変わる可能性があるため、既存の利用者を事前に確認してください。
content.routeQuery 内のワークスペース、クエリ、または自己入力の権限フィールドは認可を構成しません。range を安全に構築できない場合は 403 を返し、再生成を要求します。相対時間 15m は特定の 15 分間を固定するものではありません。固定ウィンドウが必要な場合は、ページがサポートする絶対ミリ秒範囲を使用してください。本体が先に送信され、その後でダッシュボード概要が付加される場合があります。500 は未保存を証明しないため、まず type/name で一覧を確認し、意図しない上書きを避けてください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| content.routeName | string | コンソールのルート識別子。例としてログエクスプローラーの Log、ヒートマップの RumHeatMap など。トップレベルの type との互換性を保ちます。 例: Log取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeParams | json | 対応するページのパスパラメータオブジェクト。 例: {"source": "all"}取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeParams.source | string | ログエクスプローラーでは通常 all を使用し、具体的な値はソースページによって決まります。 例: all取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeParams.カスタムキー | any | ページパスの動的パラメータ。現在のコンソールページで生成される設定に従います。 例: value取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeQuery | json | 対応するページの Query 状態。オブジェクトである必要があります。任意のクライアントクエリ値によって、サーバー側で取得済みの認可が拡大することはありません。 例: {"w": "wksp_example", "time": "1785423600000,1785427200000", "query": "service:payment", "cols": "time,message,service", "viewType": "view", "index": "default", "snapshotName": "支付服务日志"}取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeQuery.w | string | ページのワークスペース識別子。通常は現在のワークスペースです。これによって API Key のスコープを変更することはできません。 例: wksp_example取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeQuery.workspaceUUID | string | ページが必要とするクエリ対象ワークスペースのリスト(カンマ区切り)。実際のクロスワークスペース認可とスナップショット保存範囲による制限を引き続き受けます。 例: wksp_example取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeQuery.time | string | ページの時間範囲。15m、または開始ミリ秒,終了ミリ秒の文字列など。相対時間はデータを物理的に固定するものではありません。 例: 1785423600000,1785427200000取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeQuery.query | string | ページの検索クエリ文字列。ログエクスプローラーの例は service:payment です。スナップショット API が実行する DQL ではありません。 例: service:payment取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeQuery.cols | string | 表示フィールド名のカンマ区切り。例: time,message,service。 例: time,message,service取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeQuery.viewType | string | ログエクスプローラーで一般的な view(リスト)/analyze(分析)。現在のページの実際のプロトコルに従います。 例: view取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeQuery.index | string | ログインデックス名のカンマ区切り。ログインデックス設定から取得します。読み取り権限は変更しません。 例: default取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeQuery.snapshotName | string | ページに表示されるスナップショット名。トップレベルの name と一致させることを推奨します。 例: 支付服务日志取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeQuery.dashboard_id | string | ダッシュボードスナップショットに対応する dsbd_ UUID。可視性概要に使用します。事前に現在のワークスペースで認可されたリソースを確認してください。 例: dsbd_example取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeQuery.app_id | string | RUM ヒートマップの公開 appId。アプリ概要の付加に使用します。 例: payment_web取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.routeQuery.カスタムキー | any | ページのフィルター/レイアウトなどの動的状態。バックエンドは主に保存するだけで、レンダリング可能性は検証しません。 例: value取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content.カスタムキー | any | 対応するページのその他の保存状態。クライアントがサーバー側権限を注入できることを意味しません。 例: value取得または入力方法: 対応するソースページまたは既存スナップショットの content から取得します。ワークスペース/リソース ID は、事前に現在のアクセス認可を確認する必要があります。 |
|
| content | json | Y | 必須の JSON オブジェクト。エクスポートデータではなく、ページ設定/クエリ条件を保存します。オブジェクトの動的子フィールドは完全には検証されません。routeQuery/routeParams はオブジェクトである必要があり、誤った形状は保存後の読み取り/共有で 500 を引き起こす可能性があります。既存の同名スナップショットの content を全体上書きします。クライアントの content/meta 内の roles/rules/deniedNamespaces によってサーバー側権限が拡大することはありません。 null を許可: False 例: {"routeName": "Log", "routeParams": {"source": "all"}, "routeQuery": {"w": "wksp_example", "time": "1785423600000,1785427200000", "query": "service:payment", "cols": "time,message,service", "viewType": "view", "index": "default", "snapshotName": "支付服务日志"}}取得または入力方法: 現在のコンソールの対応ページからルート/フィルター状態を取得するか、既存スナップショットの content をテンプレートとして構築します。 |
| filterType | string | 任意の文字列。作成時に省略すると空になり、エンティティは 64 文字です。既存の同名同 type オブジェクトを強制上書きする場合、このフィールドは無視され、以前の値が保持されます。 null を許可: False 例: 取得または入力方法: ソースページのスナップショットフィルター分類から取得します。省略可能です。 |
|
| isForce | boolean | 任意のブール値。省略時は false です。同一ワークスペース、同一 type、同一 name で false の場合は 400 を返します。true の場合は元の uuid を再利用し、content、accountUUID、クエリ認可範囲、isPublic を上書きして createAt/updateAt を更新しますが、元の name/type/filterType/creator は保持します。他者が作成した同名設定を上書きする可能性があるため、呼び出し元は対象と共有への影響を事前に確認する必要があります。 null を許可: False 例: false取得または入力方法: 同名同 type のスナップショットを再構築すると確認した場合にのみ true を設定し、事前に旧 content と範囲のバックアップを保存してください。 |
|
| name | string | Y | 必須の文字列。現在の宣言では非空/最大長を強制していません。エンティティは 128 文字で、1~128 を推奨します。同一ワークスペース、同一 type、同一 name は上書きチェックの対象になりますが、ワークスペース全体のすべての type で一意になるわけではありません。 null を許可: False 例: 支付服务日志取得または入力方法: 呼び出し元が識別可能な名前を選択します。同 type の既存スナップショットから重複名を確認できます。 |
| type | string | Y | 必須の文字列。保存側に固定の列挙はありませんが、フロントエンドがそのページタイプをサポートしている場合にのみ開けます。任意の新規 type の保存が成功したからといって、レンダリング可能と判断してはいけません。 null を許可: False 例: Log取得または入力方法: ソースコンソールページのスナップショット設定、または既存の同ページスナップショットの type から取得します。ログエクスプローラーでは通常 Log を使用します。 |
パラメータ補足説明¶
スナップショットはページ設定とサーバー側クエリ範囲を保存します。インターネット共有には別途共有設定を作成する必要があります。snap_、share_、初回ホップ code、2 段階目 token はそれぞれ異なる識別子です。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/snapshots/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"支付服务日志","type":"Log","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":"支付服务日志"}},"isForce":false}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | 保存されたスナップショットエンティティおよび任意の関連概要。 |
| content.id | integer または null | データベース行 ID。パス定位には使用しません。送信前のスナップショットでは null の可能性があります。 |
| content.uuid | string | スナップショット UUID。snap_ プレフィックス付き。 |
| content.status | integer | リソース状態。通常は 0 で、論理削除の 3 はクエリから除外されます。 |
| content.creator | string | 最初に作成したプリンシパルの UUID。強制上書きでは creator が変更されない場合があります。現在の権限保有者は accountUUID を確認します。 |
| content.updator | string | 直近で上書き/削除更新したプリンシパル。 |
| content.createAt | number | Unix 秒の作成/再生成時刻。強制上書きでは time.time() を使用するため、レスポンスに小数が含まれる場合があります。 |
| content.updateAt | integer | Unix 秒の更新時刻。未更新の場合は -1 になることがあります。 |
| content.deleteAt | integer | Unix 秒の削除時刻。未削除の場合は通常 -1 です。 |
| content.workspaceUUID | string | 現在の Key が属するワークスペース。 |
| content.name | string | スナップショット名。同一ワークスペース、同一 type で一意に照合されます。 |
| content.type | string | ページスナップショットの種類(Log など)。保存側に公開された列挙による検証はありません。 |
| content.filterType | string | 保存されたフィルター分類。作成時に省略すると空になります。同名を強制上書きする場合、このフィールドは更新されません。 |
| content.isPublic | integer | 1 はワークスペース内での公開表示、0 はプライベートです。インターネットへの公開共有ではありません。この公開作成ではデフォルトで 1 に固定され、isPublic パラメータを受け付けません。 |
| content.isHidden | integer | 非表示フラグ。0 の場合はこの一覧に表示され、非表示のレポートスナップショットは一覧に表示されません。 |
| content.accountUUID | string | 生成時/直近の強制上書き時に権限を収集したプリンシパルの UUID。creator と異なる場合があります。 |
| content.content | object | 保存されたページ/クエリ設定。実際のテレメトリデータのコピーではありません。動的フィールドは対応するページのプロトコルに従って解釈されます。 |
| content.content.routeName | string | コンソールのルート識別子。例としてログエクスプローラーの Log、ヒートマップの RumHeatMap など。トップレベルの type との互換性を保ちます。 |
| content.content.routeParams | object | 対応するページのパスパラメータオブジェクト。 |
| content.content.routeParams.source | string | ログエクスプローラーでは通常 all を使用し、具体的な値はソースページによって決まります。 |
| content.content.routeParams.その他のキー | JSON | ページパスの動的パラメータ。現在のコンソールページで生成される設定に従います。 |
| content.content.routeQuery | object | 対応するページの Query 状態。オブジェクトである必要があります。任意のクライアントクエリ値によって、サーバー側で取得済みの認可が拡大することはありません。 |
| content.content.routeQuery.w | string | ページのワークスペース識別子。通常は現在のワークスペースです。これによって API Key のスコープを変更することはできません。 |
| content.content.routeQuery.workspaceUUID | string | ページが必要とするクエリ対象ワークスペースのリスト(カンマ区切り)。実際のクロスワークスペース認可とスナップショット保存範囲による制限を引き続き受けます。 |
| content.content.routeQuery.time | string | ページの時間範囲。15m、または開始ミリ秒,終了ミリ秒の文字列など。相対時間はデータを物理的に固定するものではありません。 |
| content.content.routeQuery.query | string | ページの検索クエリ文字列。ログエクスプローラーの例は service:payment です。スナップショット API が実行する DQL ではありません。 |
| content.content.routeQuery.cols | string | 表示フィールド名のカンマ区切り。例: time,message,service。 |
| content.content.routeQuery.viewType | string | ログエクスプローラーで一般的な view(リスト)/analyze(分析)。現在のページの実際のプロトコルに従います。 |
| content.content.routeQuery.index | string | ログインデックス名のカンマ区切り。ログインデックス設定から取得します。読み取り権限は変更しません。 |
| content.content.routeQuery.snapshotName | string | ページに表示されるスナップショット名。トップレベルの name と一致させることを推奨します。 |
| content.content.routeQuery.dashboard_id | string | ダッシュボードスナップショットに対応する dsbd_ UUID。可視性概要に使用します。事前に現在のワークスペースの認可済みリソースを確認してください。 |
| content.content.routeQuery.app_id | string | RUM ヒートマップの公開 appId。アプリ概要の付加に使用します。 |
| content.content.routeQuery.status | integer | 一覧の type=RumHeatMap の場合、現在の RUM 設定状態が付加されることがあります。履歴上削除済みのものでも現れる場合があります。 |
| content.content.routeQuery.jsonContent | object | RUM ヒートマップ一覧でのみ付加される可能性があるアプリの jsonContent。 |
| content.content.routeQuery.jsonContent.name | string | アプリ名。 |
| content.content.routeQuery.jsonContent.type | string | アプリのプラットフォームタイプ。 |
| content.content.routeQuery.jsonContent.extend | object | 任意のアプリ拡張。 |
| content.content.routeQuery.jsonContent.extend.カスタムキー | JSON | アプリが保存する拡張値。 |
| content.content.routeQuery.その他のキー | JSON | ページのフィルター/レイアウトなどの動的状態。バックエンドは主に保存するだけで、レンダリング可能性は検証しません。 |
| content.content.その他のキー | JSON | 対応するページのその他の保存状態。クライアントがサーバー側権限を注入できることを意味しません。 |
| content.rules | object または null | サーバー側で収集されたクエリ権限/マスキングのスナップショット。読み取り専用です。クライアントは権限を得るために rules を送信したり、content 内で偽造したりしてはいけません。履歴形式は異なる場合があります。 |
| content.rules.eventScopeVersion | integer | 新しい認可イベント範囲のバージョン 1。古いスナップショットにはこのキーがない場合があり、特定のクエリでは再生成が要求されます。 |
| content.rules.ruleContextVersion | integer | 新形式は 2、旧形式は 1 または未指定の場合があります。 |
| content.rules.roles | array<string> |
保存時に実際に呼び出した身分のロール識別子。書き込み可能なロール選択ではありません。 |
| content.rules.roles[] | string | サーバーが確認した単一のロール ID。 |
| content.rules.deniedNamespaces | array<string> |
クエリ禁止範囲。例: logging/rum/tracing/metric/lineage/keyevent。実際の値はサイトで認識されている namespace に準じます。 |
| content.rules.deniedNamespaces[] | string | 単一の禁止データ範囲。 |
| content.rules.rules | object | namespace→取得済みデータアクセスルールの配列。 |
| content.rules.rules.名前空間 | array<object> |
その範囲のルール。空配列はクエリ権限の代わりにはなりません。 |
| content.rules.rules.名前空間[].rule_uuid | string | 元のアクセスルール UUID。 |
| content.rules.rules.名前空間[].region_code | string | ルールが存在するサイト識別子。 |
| content.rules.rules.名前空間[].rule_info | object | アクセス条件の内容。データ範囲に従って解釈されます。 |
| content.rules.rules.名前空間[].rule_info.sources | array<string> |
lineage/keyevent などの範囲で許可されるソース。元のルールプロトコルに従います。 |
| content.rules.rules.名前空間[].rule_info.sources[] | string | 単一の元ルールソース。クライアントによる新しい認可ではありません。 |
| content.rules.rules.名前空間[].rule_info.rule | string | 元ルールのフィルター式。 |
| content.rules.rules.名前空間[].rule_info.その他のキー | JSON | その範囲の元データルールのその他のフィールド。 |
| content.rules.rules.名前空間[].rule_mask_info | object | 元のデータアクセスルールに付随する任意のマスキング情報。 |
| content.rules.rules.名前空間[].rule_mask_info.maskFields | string | カンマ区切りのフィールド。 |
| content.rules.rules.名前空間[].rule_mask_info.reExprs | array<object> |
正規表現設定。 |
| content.rules.rules.名前空間[].rule_mask_info.reExprs[].reExpr | string | マスキング正規表現。 |
| content.rules.rules.名前空間[].その他のキー | JSON | 元のアクセスルールの予約フィールド。この API で新たに実行するパラメータではありません。 |
| content.rules.sensitiveDataMaskRules | object | namespace→機密フィールドルールの配列(履歴上の空オブジェクトと互換)。 |
| content.rules.sensitiveDataMaskRules.名前空間 | array または object | 新形式で非空の場合はルールオブジェクトの配列である必要があります。空オブジェクトはルールなしとして互換処理されます。 |
| content.rules.sensitiveDataMaskRules.名前空間[].fields | array<string> |
元の機密フィールドリスト。 |
| content.rules.sensitiveDataMaskRules.名前空間[].fields[] | string | フィールド名。 |
| content.rules.sensitiveDataMaskRules.名前空間[].reExpr | string または null | 元の機密データマスキング正規表現。 |
| content.rules.sensitiveDataMaskRules.名前空間[].その他のキー | JSON | 元ルールのその他のフィールド。 |
| content.dashboardIsPublic | integer または boolean | 任意の関連ダッシュボード可視性ヒント。関連ダッシュボードが存在する場合にのみ付加される可能性があります。スナップショットの共有権限とは異なります。 |
| content.declaration | object または null | 現在のワークスペースの公開宣言。 |
{
"code": 200,
"content": {
"id": null,
"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": []
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては、共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンス説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落しているか、フィールド値が宣言された検証条件に違反しています | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | リクエスト JSON のトップレベルがオブジェクトではありません | 一部の json ファイル形式エラー | content オブジェクトを含むスナップショットパラメータを送信してください。 |
| 400 | ft.SnapshotRepeatNames | ワークスペース内に同一 type・同一 name のレコードが存在し、isForce が有効になっていません | スナップショット名の重複 | まず対象を照会し、上書きの影響を確認したうえで明示的に isForce=true を指定してください。 |
| 403 | ft.SnapshotQueryScopeUnavailable | 現在のサーバー側認可/ルールコンテキストを安全に取得または検証できません | 共有アクセス範囲が不完全、またはこのクエリが許可されていません。共有者に再生成を依頼してください | 管理者が現在の Key のクエリ権限/ルールを確認し、対象範囲を持つ有効な身分で再生成してください。content に権限を注入してバイパスすることはできません。 |
| 401 | ft.WKSPNotExistOrReleased | 作成時に現在のアクティブワークスペースの読み取りに失敗しました | ワークスペースが存在しない、または解放済みです | Key のワークスペースがまだアクティブか確認してください。 |
| 500 | ft.InternalServerError | スナップショット/権限ルールの読み書き、保存後の関連ダッシュボード概要またはコンテキスト送信などで未処理の例外が発生しました | 内部エラー | まず type/name でスナップショットを読み取り、保存済みの content/認可範囲を確認して、無闇な isForce 上書きを避けてください。traceId を保持して特定してください。 |