コンテンツにスキップ

インポート



POST /api/v1/dashboards/{dashboard_uuid}/import

概要

テンプレートで指定したダッシュボードの内容を上書きし、対象ダッシュボードの UUID を保持します。

呼び出し前の準備と使用手順

まずダッシュボードのエクスポートで対象ダッシュボードをバックアップし、インポートするテンプレートを検証してください。main を含む完全なオブジェクトを渡します。ダッシュボード UUID は保持されます。既存のチャート、変数、グループは先に削除され、テンプレートから再作成されるため、チャートには新しい UUID が付与されます。テンプレートは最初に検証され、削除と再作成は同一トランザクション内で完了します。失敗した場合は、まず詳細を確認して現在の内容をエクスポートし、バックアップに基づいて復旧してください。

ルートパラメータ

パラメータ名 型 必須 説明
dashboard_uuid string Y 対象ダッシュボードの UUID。
例: dsbd_example
取得・記入方法: ダッシュボード一覧の content.data[].uuid からコピーするか、作成結果の content.uuid を使用します。

リクエストヘッダ

パラメータ名 型 必須 説明
DF-API-KEY string Y ワークスペースの OpenAPI 認証情報。
例: <DF-API-KEY>
取得・記入方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。

Body リクエストパラメータ

パラメータ名 型 必須 説明
templateInfo json Y 業務上必須のテンプレートオブジェクト。省略するとテンプレート不足エラーが返されます。空オブジェクトで試さないでください。空オブジェクトは内容をクリアする可能性があります。
null 許容: False
例: {"title": "生产巡检更新", "summary": "生产服务巡检指标", "identifier": "prod-check-updated", "dashboardType": "CUSTOM", "dashboardExtend": {}, "dashboardMapping": [], "iconSet": {}, "dashboardBindSet": [], "main": {"type": "template", "charts": [], "vars": [], "chartGroupPos": [], "groups": []}}
取得・記入方法: ダッシュボードのエクスポートを呼び出し、実際のレスポンスの content オブジェクトを使用します。ワークスペースをまたいでインポートした後は、変数、データソース、権限を確認してください。
specifyDashboardUUID string 互換フィールドです。現在のインポートルートではこのフィールドは読み取られません。
null 許容: False
空文字列許容: False
$matchRegExp: ^dsbd_custom_[a-z0-9]{32}$
例: dsbd_custom_1234567890abcdef1234567890abcdef
取得・記入方法: 新しい UUID を定義する必要がある場合は作成 API を使用してください。インポート時はパス内の対象 UUID を使用します。

パラメータ補足説明

ダッシュボードテンプレートはエクスポート API の content を使用します。main.charts、main.vars、main.groups をそのまま再利用できます。ワークスペースをまたぐ場合はデータソースを再確認してください。

テンプレートフィールド 記入方法
title、summary、identifier テンプレートのタイトル、サマリー、カスタム識別子。新規作成時はトップレベルの name と identifier が新しい値を決定し、トップレベルの desc が空または省略されている場合はテンプレートの summary を使用します。インポート時はテンプレートの非空値のみが現在値を上書きします。
dashboardType、dashboardExtend、dashboardMapping ダッシュボードタイプ、拡張オブジェクト、変数マッピング。非空のテンプレートではテンプレート内の拡張とマッピングを使用します。
iconSet アイコン設定オブジェクト。既存の url や icon を含め、エクスポート内容をそのまま流用できます。
main.vars 変数定義の配列。送信順に作成されます。
main.vars[].name、code 変数の表示名とクエリで参照するキー。同じエクスポートテンプレートからコピーして、既存のクエリが参照を失わないようにしてください。省略時は空文字列です。
main.vars[].type、datasource 変数のタイプとデータソース。同じタイプの変数のエクスポート値をコピーします。type は大文字に変換されます。
main.vars[].definition 変数の値設定。形式は変数タイプによって異なるため、同種の変数のエクスポート構造に従って記入します。省略時は {} です。
main.vars[].multiple、includeStar 複数選択をサポートするか、ワイルドカードオプションを含めるかをそれぞれ制御します。デフォルトは true です。
main.vars[].hide、isHiddenAsterisk 変数とワイルドカードオプションの非表示状態を制御します。デフォルトは 0 です。
main.vars[].valueSort、extend 選択可能値の並び順と拡張設定。エクスポートテンプレートを流用し、省略時はそれぞれ空文字列と空オブジェクトになります。
main.groups チャートグループの配列。名前の文字列、または name と任意の extend を含むオブジェクトを使用できます。同じ名前は一度だけ作成されます。
main.charts チャート定義の配列。インポート時は既存のチャート UUID を無視し、再作成します。
main.charts[].name、type チャート名とチャートタイプ。名前は最大 256 文字、デフォルトは空です。type のデフォルトは line で、エクスポートから実際のタイプをコピーできます。
main.charts[].queries、extend クエリと拡張設定。内部構造はチャートタイプによって異なるため、同じタイプのチャートのエクスポートオブジェクトを再利用することを推奨します。省略時はそれぞれ [] と {} です。
main.charts[].pos チャートレイアウトオブジェクト。エクスポート項目の i、x、y、w、h を再利用できます。
main.charts[].group グループ名の文字列、または name を含むオブジェクト。名前は main.groups 内の名前に対応します。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/dashboards/dsbd_example/import' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"templateInfo":{"title":"生产巡检更新","summary":"生产服务巡检指标","identifier":"prod-check-updated","dashboardType":"CUSTOM","dashboardExtend":{},"dashboardMapping":[],"iconSet":{},"dashboardBindSet":[],"main":{"type":"template","charts":[],"vars":[],"chartGroupPos":[],"groups":[]}}}'

レスポンス

HTTP 200、application/json。以下の例は直接読み取れる主要なフィールドを示します。

フィールド 型 説明
content.id integer ダッシュボードのレコード番号。
content.uuid string ダッシュボード UUID。詳細、変更、削除、カルーセル表示に使用します。
content.workspaceUUID string 所属ワークスペース。
content.name string ダッシュボードの表示名。
content.desc string ダッシュボードの説明。
content.identifier string 対外的なカスタム識別子。空の場合があります。
content.ownerType string リソースタイプの所属。ダッシュボードは通常 node です。
content.type string ダッシュボードタイプ。例: CUSTOM。
content.chartPos array<object> チャートレイアウトの配列。各項目の chartUUID はチャート識別子、pos はレイアウトオブジェクトです。
content.chartPos[].chartUUID string 関連付け済みのチャート UUID。
content.chartPos[].pos object チャートのサイズと位置。例: x、y、w、h。
content.chartGroupPos array<string> チャートグループ識別子の並び順。
content.iconSet object アイコン設定。
content.isPublic integer 1 は公開、0 は作成した身元のみ表示、-1 はカスタム権限。
content.extend object 拡張設定。
content.mapping array<object> 変数フィールドのマッピング。
content.createdWay string リソースの作成元。
content.dashboardBindSet array ビューのバインド設定。
content.openPermissionSet boolean 現在カスタム権限が有効かどうか。
content.permissionSet array<string> 操作権限の主体 UUID リスト。
content.readPermissionSet array<string> 読み取り権限の主体 UUID リスト。
content.tagInfo array<object> このレスポンスに関連するタグ情報。
content.tagInfo[].id string タグ識別子。uuid と同じです。
content.tagInfo[].uuid string タグ UUID。
content.tagInfo[].name string 関連付けられたタグ名。
content.tagInfo[].description string タグの説明。
content.tagInfo[].colour string タグの色。
content.tagInfo[].scope array<string> タグの有効範囲。
content.tagInfo[].tagPermissionInfo object タグの認可が存在する場合に付与される操作権限と読み取り権限の情報。
content.status integer レコードのステータス。
content.creator string 作成者の身元 ID。
content.updator string 最終更新者の身元 ID。更新がない場合は空になることがあります。
content.createAt number 作成時間。Unix 秒。
content.updateAt number 最終更新時間。Unix 秒。更新がない場合は -1 になることがあります。
content.deleteAt number 削除時間。Unix 秒。未削除の場合は -1。
content.creatorInfo object 作成者情報。空オブジェクトの場合があります。
content.updatorInfo object 最終更新者情報。空オブジェクトの場合があります。
content.declaration object または null ワークスペースの共通宣言。
content.skippedTags array<object> 一部のタグがスコープ不一致でスキップされた場合に返されます。
content.skippedTags[].name string スキップされたタグ名。
content.skippedTags[].scope array<string> 既存タグのスコープ。
content.skippedTags[].expectedScope string 現在のリソースが期待するタグスコープ。
content.skippedTags[].reason string タグがスキップされた理由。
{
  "code": 200,
  "content": {
    "id": 21,
    "uuid": "dsbd_example",
    "name": "生产巡检更新",
    "desc": "生产服务巡检指标",
    "workspaceUUID": "wksp_example",
    "identifier": "prod-check-updated",
    "ownerType": "node",
    "type": "CUSTOM",
    "chartPos": [],
    "chartGroupPos": [],
    "iconSet": {},
    "isPublic": 1,
    "extend": {},
    "mapping": [],
    "createdWay": "import",
    "dashboardBindSet": [],
    "openPermissionSet": false,
    "permissionSet": [],
    "readPermissionSet": [],
    "tagInfo": [],
    "creator": "wsak_example",
    "updator": "",
    "createAt": 1785427200,
    "updateAt": -1,
    "deleteAt": -1,
    "status": 0,
    "declaration": {},
    "creatorInfo": {},
    "updatorInfo": {}
  },
  "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 ファイルの形式エラー パラメータを JSON オブジェクト内に配置してください。
404 ft.NotFoundView 対象ダッシュボードが存在しない、削除済み、または現在のワークスペースにない 指定されたビューが見つかりません 現在のワークスペースのダッシュボード一覧が返す UUID に切り替えてください。
403 ft.ForbiddenDashboardOperation 呼び出し元の身元が対象ダッシュボードを操作できない ダッシュボード【{}】の操作権限がありません ダッシュボードの可視範囲、操作権限、使用している API Key を確認してください。
403 ft.ForbiddenFreeEditionLimit 対象ワークスペースで対応する数量制限が有効であり、現在の数量が上限に達している 無料プランのワークスペース {} は上限({} 個)に達したため、新規作成できません。商用プランにアップグレードすると制限が解除されます ワークスペースのクォータを確認し、現在の数量と目的の操作に応じて調整した後に再試行してください。
400 ft.IdentificationIdExists テンプレートのカスタム識別子が他の同種ダッシュボードで既に使用されている 識別子 ID は既に存在します テンプレートの identifier を変更してから再送信してください。
406 ft.ExceedMaxCharacterLimit テンプレート内のチャート、チャートグループ、またはタグ名がフィールドの上限を超えている {}が最大文字長制限を超えています チャート名とグループ名を 256 文字以内、タグ名を 128 文字以内に短縮してから、テンプレートを再確認してください。
406 ft.MissingImportTemplateResourceUUID テンプレートオブジェクトが提供されていない インポートテンプレート/インポート元ビュー UUID が不足しています エクスポートレスポンスから完全な content を取得し、templateInfo に設定してください。
406 ft.InvalidParameter テンプレート構造が無効。例: main がオブジェクトでない、charts、vars、groups が配列でない、またはチャートのクエリ構造が無効 パラメータ{}が無効です エラーで示されたフィールドパスに従ってテンプレートを修正してください。本バージョンのエクスポート API が返す完全なテンプレートを優先的に使用してください。

フィードバック

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