コンテンツにスキップ

作成



POST /api/v1/dashboards/create

概要

ダッシュボードを作成し、リソース識別子を返します。テンプレートからの初期化に対応しています。

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

名前を送信すると空のダッシュボードを作成できます。レイアウトを引き継ぐ場合は、ダッシュボードのエクスポートからテンプレート内容を取得し、templateInfo に入力します。作成に成功したら content.uuid を保存します。名前またはカスタム識別子が競合した場合、デフォルトでは HTTP 200 で content.repeatInfo が返されるため、クライアント側で実際に作成されたかを確認してください。recoverIdentifier=true を指定すると、該当する既存のダッシュボードを先に削除してから作成を試みます。実行前に必ずエクスポートしてバックアップし、競合する各オブジェクトの UUID を確認してください。失敗した場合は現在の状態を照会します。

リクエストヘッダー

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

Body リクエストパラメータ

パラメータ名 型 必須 説明
name string Y ダッシュボードの表示名。
null 許可: False
最大長: 128
例: 生产巡检
取得または入力方法: 現在のワークスペース内で他のダッシュボードに使用されていない名前を使用します。
desc string 作成時の説明。
null 許可: False
空文字列の許可: True
最大長: 2048
例: 生产服务巡检指标
取得または入力方法: ダッシュボードの用途を入力します。テンプレート使用時に省略または空を渡した場合は、テンプレートの summary が使用されます。
recoverIdentifier boolean デフォルトは false で、競合の詳細を返します。true の場合は競合するオブジェクトを先に削除します。
null 許可: False
例: false
取得または入力方法: 最初の送信では false のままにします。repeatInfo を取得した後、該当するダッシュボードを削除すると確認できた場合のみ true を設定します。
identifier string カスタム識別子 ID。最大 128 文字。この値と UUID は別々に使用します。
null 許可: False
空文字列の許可: True
最大長: 128
例: prod-check
取得または入力方法: 呼び出し側の命名規則に従い、このワークスペース内で他のダッシュボードに使用されていない識別子を指定します。
extend json ダッシュボードの拡張設定。必要に応じて既存のフィールドを再利用します。
null 許可: False
例: {}
取得または入力方法: ダッシュボード詳細の content.extend から既存のオブジェクトを取得します。
mapping array ダッシュボード変数のフィールドマッピング配列。マッピングがない場合は空配列を渡せます。
null 許可: False
例: []
取得または入力方法: 既存ダッシュボードの content.mapping、またはエクスポートしたテンプレートの content.dashboardMapping から値を取得します。
tagNames array シーンタグ名の配列。空の場合でもテンプレートの tagInfo が使用されることがあります。タグなしのダッシュボードを作成する場合は、テンプレート内の関連タグも併せてクリアしてください。
null 許可: False
例: ["team:ops"]
取得または入力方法: ダッシュボード詳細の content.tagInfo[].name からコピーするか、関連付けるタグ名を入力します。
templateInfo json ダッシュボードテンプレートオブジェクト。main.charts、main.vars、main.groups が内容を定義します。
null 許可: False
空文字列の許可: False
例: {"title": "生产巡检", "summary": "生产服务巡检指标", "identifier": "prod-check", "dashboardType": "CUSTOM", "dashboardExtend": {}, "dashboardMapping": [], "iconSet": {}, "dashboardBindSet": [], "main": {"type": "template", "charts": [], "vars": [], "chartGroupPos": [], "groups": []}}
取得または入力方法: ダッシュボードのエクスポートを呼び出し、実際のレスポンスの content オブジェクトを使用します。ワークスペースをまたいでインポートした後は、変数、データソース、権限を確認してください。
specifyDashboardUUID string 任意指定の新規ダッシュボード UUID。完全な形式は dsbd_custom_ の後に 32 桁の小文字英数字です。
null 許可: False
空文字列の許可: False
$matchRegExp: ^dsbd_custom_[a-z0-9]{32}$
例: dsbd_custom_1234567890abcdef1234567890abcdef
取得または入力方法: クライアントで 32 桁の小文字英数字を生成し、dsbd_custom_ を連結します。必ず未使用であることを事前に確認してください。
isPublic int 1 は公開、0 は作成した本人のみ表示、-1 はカスタム権限です。作成時に指定しない場合は 1 がデフォルトです。
null 許可: False
例: 1
取得または入力方法: 目的の可視範囲に応じて 1、0、-1 のいずれかを選択します。
openPermissionSet boolean 過去互換性のためのフィールドです。現在の作成処理では isPublic によってカスタム権限を有効にするかが決まります。
null 許可: False
例: false
取得または入力方法: 旧クライアントとの互換用です。新しい設定では isPublic=-1 を使用します。
permissionSet array isPublic=-1 の場合に使用する操作権限のリスト。ロール(オーナーを除く)、メンバー、チームの UUID を含められます。
null 許可: False
例: ["role_example"]
取得または入力方法: ロール一覧、メンバー一覧、またはチーム一覧から UUID を取得します。
readPermissionSet array isPublic=-1 の場合に使用する読み取り権限のリスト。ロール(オーナーを除く)、メンバー、チームの UUID を含められます。
null 許可: False
例: ["role_example"]
取得または入力方法: ロール一覧、メンバー一覧、またはチーム一覧から 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 を含むオブジェクトを使用できます。同じ名前は 1 回だけ作成されます。
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 内の名前に対応します。

空のダッシュボードを作成する場合は、トップレベルの extend と mapping を使用できます。権限はトップレベルの isPublic とリストで決定されます。トップレベルの tagNames を優先して使用し、未入力または空の場合でもテンプレートの tagInfo を引き継げます。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/dashboards/create' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"name":"生产巡检","desc":"生产服务巡检指标","identifier":"prod-check","isPublic":1}'

レスポンス

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.declaration object または null ワークスペースの共通宣言。
content.repeatInfo object デフォルトで競合を処理した場合に返されます。名前、識別子、および両方の競合でグループ化され、このレスポンスには新しい UUID は含まれません。
content.repeatInfo.name_and_identifier array<object> 名前と識別子の両方が一致した競合項目。
content.repeatInfo.name array<object> 名前の競合項目。
content.repeatInfo.identifier array<object> 識別子の競合項目。
content.repeatInfo.*[].conflictUUIDs array<string> その競合に関わるすべての既存ダッシュボードの UUID。
content.repeatInfo.*[].isCrossConflict boolean 名前と識別子がそれぞれ 2 つの異なるオブジェクトに一致したかどうか。
{
  "code": 200,
  "content": {
    "id": 21,
    "uuid": "dsbd_example",
    "name": "生产巡检",
    "desc": "生产服务巡检指标",
    "workspaceUUID": "wksp_example",
    "identifier": "prod-check",
    "ownerType": "node",
    "type": "CUSTOM",
    "chartPos": [],
    "chartGroupPos": [],
    "iconSet": {},
    "isPublic": 1,
    "extend": {},
    "mapping": [],
    "createdWay": "manual",
    "dashboardBindSet": [],
    "openPermissionSet": false,
    "permissionSet": [],
    "readPermissionSet": [],
    "tagInfo": [],
    "creator": "wsak_example",
    "updator": "",
    "createAt": 1785427200,
    "updateAt": -1,
    "deleteAt": -1,
    "status": 0,
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

名前と識別子の両方が競合した場合の HTTP 200 レスポンス

{
  "code": 200,
  "content": {
    "repeatInfo": {
      "name_and_identifier": [
        {
          "name": "生产巡检",
          "identifier": "prod-check",
          "fileName": "",
          "importName": "生产巡检",
          "importIdentifier": "prod-check",
          "existName": "生产巡检",
          "existIdentifier": "prod-check",
          "nameConflictUUID": "dsbd_example",
          "identifierConflictUUID": "dsbd_example",
          "existNameIdentifier": "prod-check",
          "existIdentifierName": "生产巡检",
          "isCrossConflict": false,
          "conflictUUIDs": [
            "dsbd_example"
          ]
        }
      ],
      "name": [],
      "identifier": []
    },
    "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 ファイルのフォーマットが誤っています パラメータを JSON オブジェクト内に配置します。
400 ft.IdentificationIdExists 指定した新規 UUID が既に使用されている 識別子 ID は既に存在します 未使用の新規 UUID を選択するか、このフィールドを省略してサービス側に割り当てさせます。
403 ft.ForbiddenDashboardOperation 呼び出し元の識別情報が対象ダッシュボードを操作できない ダッシュボード【{}】の操作権限がありません ダッシュボードの可視範囲、操作権限、使用している API Key を確認します。
403 ft.ForbiddenFreeEditionLimit 対象ワークスペースで該当する数量制限が有効になっており、現在の数量が上限に達している 無料プランワークスペース {} は上限( {} 個)に達したため、新規作成できません。商用プランにアップグレードすると制限が解除されます ワークスペースのクォータを確認し、現在の数量と目的の操作に応じて調整したうえで再試行します。
400 ft.TagScopeMismatch タグ名は既に存在するが、そのスコープがシーンタグと互換性がない メッセージにはタグ名とスコープが含まれます。例: team:ops: ['monitor'] -> scene。 シーンまたは汎用スコープのタグ名を選択するか、別の名前に変更します。
406 ft.ExceedMaxCharacterLimit テンプレート内のグラフ、グラフグループ、タグの名前がフィールドの上限を超えている {}が最大文字数制限を超えています グラフとグループの名前を 256 文字以内、タグ名を 128 文字以内に短縮し、テンプレートを再確認します。
406 ft.InvalidParameter 指定した UUID が運用エントリで認識されない パラメータ{}が無効です dsbd_custom_ の後に 32 桁の小文字英数字を指定するか、省略してシステムに生成させます。
406 ft.InvalidParameter テンプレート構造が無効。例えば main がオブジェクトでない、charts、vars、groups が配列でない、グラフのクエリ構造が無効など パラメータ{}が無効です エラーで示されたフィールドパスに従ってテンプレートを修正します。本バージョンのエクスポート API が返す完全なテンプレートを優先して使用してください。

フィードバック

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