コンテンツにスキップ

作成



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 を保持して特定してください。

フィードバック

このページは役に立ちましたか?