作成¶
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 が返す完全なテンプレートを優先して使用してください。 |