作成¶
POST /api/v1/dashboard/add
概要¶
ユーザーの組み込みビューを作成します。空白テンプレート、ソースビューのコピー、またはカスタムテンプレートの送信をサポートします。
呼び出し前の確認事項と使用手順¶
最小限のリクエストでは name のみが必要です。コピーする場合は、組み込みビューリストから同一ワークスペース内の有効なソースビューを選択します。sourceDashboardUUID が空でない場合は優先されます。無効なソースを指定すると、空白のビューが作成される可能性があります。名前または識別子が衝突した場合、デフォルトでは HTTP 200 で repeatInfo を返し、作成は行いません。recoverIdentifier=true は一致したすべてのビューを削除して再作成します。削除と再作成は同じトランザクションで処理されます。名前と識別子が異なるビューに一致した場合、両方のビューが削除される可能性があります。事前にバックアップし、衝突する UUID を確認してください。失敗した場合は、まず現在の状態を確認し、バックアップに従って復元してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| dashboardBidding.* | array | 属性値は、対応するフィールドのマッチ条件配列です。 例: [{"op": "in", "value": ["web-01"]}]取得または入力方法: 組み込みビューの詳細で現在のバインディングを読み取るか、ビューへ遷移する必要があるログやオブジェクトなどのデータからフィールド値を確認します。 |
|
| dashboardBidding.*[].op | string | in は指定された値のいずれかに一致し、wildcard はワイルドカードパターンで一致します。ソースフィールドの値が空でない場合、単独の * はすべての値に一致できます。複数の条件は、いずれかに一致した場合にヒットとして扱われます。 例: in取得または入力方法: 詳細でそのフィールドに設定されているマッチ方式を優先して使用します。 |
|
| dashboardBidding.*[].value | array | 文字列配列です。ワークスペースで左ワイルドカードが制限されている場合は、*example 形式の使用を避けてください。 例: ["web-01"]取得または入力方法: 元データの該当フィールドから実際の値を選択します。タグに一致させる場合は label を使用でき、元データの df_label に一致させることもできます。 |
|
| sourceDashboardUUID | string | ソースビューの UUID。空でない場合は templateInfos より優先されます。 null を許可: False 空文字列を許可: True 最大長: 128 例: dsbd_inner_example取得または入力方法: 組み込みビューリストからコピーするソースの UUID を取得し、事前に詳細を確認します。 |
|
| name | string | Y | 組み込みビューの名前。最大 256 文字です。 null を許可: False 最大長: 256 例: 主机详情内置视图取得または入力方法: 現在のワークスペース内で別の組み込みビューに使用されていない名前を入力します。 |
| desc | string | 組み込みビューの説明。最大 2048 文字です。 null を許可: False 最大長: 2048 例: 根据主机查看运行状态取得または入力方法: このビューの用途を入力します。 |
|
| recoverIdentifier | boolean | 一致した既存ビューを削除して作成を続行するかどうか。デフォルトは false です。 null を許可: False 例: false取得または入力方法: 初回リクエストでは false のままにします。バックアップし、各競合オブジェクトを置き換えることを確認した後にのみ true を入力します。 |
|
| identifier | string | 同一ワークスペース内の組み込みビューの識別子は一意である必要があります。最大 128 文字で、空でもかまいません。 null を許可: False 空文字列を許可: True 最大長: 128 例: host-overview取得または入力方法: 安定したカスタム識別子です。変更前に詳細から現在の identifier を取得できます。 |
|
| templateInfos | json | 作成に使用する JSON テンプレートオブジェクトです。 null を許可: False 空文字列を許可: False 例: {"title": "主机详情内置视图", "summary": "根据主机查看运行状态", "identifier": "", "dashboardType": "CUSTOM", "dashboardExtend": {}, "dashboardMapping": [], "dashboardBindSet": [], "iconSet": {}, "main": {"type": "template", "charts": [], "vars": [], "groups": [], "chartGroupPos": []}}取得または入力方法: 組み込みビューのエクスポートの content から取得し、main 全体を保持します。 |
|
| dashboardBidding | json | オプションのバインディング条件オブジェクトです。バインディングがない場合は省略するか、空のオブジェクトを使用します。 null を許可: False 例: {"host": [{"op": "in", "value": ["web-01"]}]}取得または入力方法: 組み込みビューの詳細で現在のバインディングを読み取るか、ビューへ遷移する必要があるログやオブジェクトなどのデータからフィールド値を確認します。 |
|
| specifyDashboardUUID | string | 新しいビューの UUID です。dsbd_custom_ で始まり、グローバルに未使用である必要があります。削除済みの UUID も再利用できません。 null を許可: False 空文字列を許可: False $matchRegExp: ^dsbd_custom_[a-z0-9]{32}$ 例: dsbd_custom_0123456789abcdef0123456789abcdef取得または入力方法: 32 文字の小文字または数字をサフィックスとして自身で生成します。通常は省略し、サービスによって割り当てられます。 |
パラメータ補足説明¶
テンプレートを使用する場合でも、トップレベルの name は必須です。identifier は省略すると空になり、テンプレート内の同名フィールドがトップレベルフィールドの代わりになることはありません。トップレベルの desc が空または省略されている場合は、テンプレートの summary で補完されます。空でないバインディングがある場合にのみ、作成レスポンスに dashboardBidding が含まれます。ワークスペース間で移行する場合は、別途バインディングを設定する必要があります。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/dashboard/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"主机详情内置视图","desc":"根据主机查看运行状态","identifier":"host-overview","dashboardBidding":{"host":[{"op":"in","value":["web-01"]}]}}'
レスポンス¶
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 | 組み込みビューのリソース帰属。組み込みビューの場合は inner です。 |
| content.type | string | 組み込みビューのタイプ。例: CUSTOM。 |
| content.isPublic | integer | 詳細のアクセス範囲。1 は公開、0 は作成者のみアクセス可能です。 |
| 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.extend | object | 組み込みビューの拡張情報。 |
| content.mapping | array<object> |
変数フィールドのマッピング情報。 |
| content.dashboardBindSet | array | ビューのバインディング設定。 |
| content.createdWay | string | リソースの作成元。 |
| content.openPermissionSet | boolean | エンティティレコードの権限設定スイッチ。 |
| content.permissionSet | array<string> |
レコード内の操作権限主体 UUID。 |
| content.readPermissionSet | array<string> |
レコード内の読み取り権限主体 UUID。 |
| 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.dashboardBidding | object | 空でないバインディングがある場合にのみ、このフィールドが返されます。 |
| content.dashboardBidding.* | array<object> |
実際のソースフィールドごとに構成されたマッチ条件配列。 |
| content.dashboardBidding.*[].op | string | マッチ演算子。 |
| content.dashboardBidding.*[].value | array<string> |
マッチ値配列。 |
| content.declaration | object または null | ワークスペースの共通宣言。 |
| content.repeatInfo | object | 名前または識別子が衝突した場合に返されます。レスポンスには新しい UUID は含まれません。 |
| content.repeatInfo.name | array<object> |
名前に一致した競合レコード。 |
| content.repeatInfo.identifier | array<object> |
識別子に一致した競合レコード。 |
| content.repeatInfo.name_and_identifier | array<object> |
名前と識別子の両方に一致した競合レコード。 |
| content.repeatInfo.*[].name | string | 作成予定のビュー名。 |
| content.repeatInfo.*[].identifier | string | 作成予定のビューの識別子。 |
| content.repeatInfo.*[].importName | string | 作成予定のビュー名。 |
| content.repeatInfo.*[].importIdentifier | string | 作成予定のビューの識別子。 |
| content.repeatInfo.*[].fileName | string | 関連するテンプレートのファイル名。直接呼び出す場合は通常空です。 |
| content.repeatInfo.*[].existName | string | 一致した既存ビューの名前。 |
| content.repeatInfo.*[].existIdentifier | string | 一致した既存ビューの識別子。 |
| content.repeatInfo.*[].nameConflictUUID | string | 名前の衝突が存在する場合の、対応する既存ビューの UUID。 |
| content.repeatInfo.*[].identifierConflictUUID | string | 識別子の衝突が存在する場合の、対応する既存ビューの UUID。 |
| content.repeatInfo.*[].existNameIdentifier | string | 名前が衝突したオブジェクトの識別子。 |
| content.repeatInfo.*[].existIdentifierName | string | 識別子が衝突したオブジェクトの名前。 |
| content.repeatInfo.*[].isCrossConflict | boolean | 名前と識別子がそれぞれ異なる 2 つのオブジェクトに一致したかどうか。 |
| content.repeatInfo.*[].conflictUUIDs | array<string> |
衝突に関係するすべての既存ビューの UUID。 |
{
"code": 200,
"content": {
"id": 72,
"uuid": "dsbd_inner_example",
"name": "主机详情内置视图",
"desc": "根据主机查看运行状态",
"workspaceUUID": "wksp_example",
"identifier": "host-overview",
"ownerType": "inner",
"type": "CUSTOM",
"isPublic": 1,
"chartPos": [],
"chartGroupPos": [],
"iconSet": {},
"extend": {},
"mapping": [],
"dashboardBindSet": [],
"createdWay": "manual",
"openPermissionSet": false,
"permissionSet": [],
"readPermissionSet": [],
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"dashboardBidding": {
"host": [
{
"op": "in",
"value": [
"web-01"
]
}
]
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
名前が衝突した場合の HTTP 200 レスポンス
{
"code": 200,
"content": {
"repeatInfo": {
"name": [
{
"name": "主机详情内置视图",
"identifier": "",
"fileName": "",
"importName": "主机详情内置视图",
"importIdentifier": "",
"existName": "主机详情内置视图",
"existIdentifier": "host-overview",
"nameConflictUUID": "dsbd_inner_example",
"existNameIdentifier": "host-overview",
"isCrossConflict": false,
"conflictUUIDs": [
"dsbd_inner_example"
]
}
],
"identifier": [],
"name_and_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 オブジェクトに含めてください。 |
| 403 | ft.ForbiddenFreeEditionLimit | 組み込みビューの数量制限が有効になっており、ワークスペースが作成上限に達しています | 無料プランのワークスペース {} は上限({} 個)に達したため、新規作成できません。商用プランに加入すると制限を解除できます | 現在のワークスペースのクォータを確認し、保持不要なビューを解放してから再試行してください。 |
| 406 | ft.ParameterCheckFailed | ワークスペースで左ワイルドカードが制限されており、バインディング値が * で始まるワイルドカード条件に一致しました | クエリ設定のあいまい一致では、左側の * 一致は現在サポートされていません | 値の先頭にある * を削除するか、完全一致の値に変更してください。この制限は、wildcard、またはフィールド名が * もしくは -* で始まる条件に適用されます。単独の * ではこの検証は発生しません。エラーレスポンスの content は true です。 |
| 400 | ft.IdentificationIdExists | 組み込みビューの識別子または新しいビューの UUID がすでに使用されています | 識別子 ID はすでに存在します | 未使用の値を使用するか、カスタム UUID を省略してサービスに生成させます。 |
| 406 | ft.ExceedMaxCharacterLimit | テンプレートのチャート名またはビューグループ名が 256 文字を超えています | {} が最大文字数制限を超えています | 対応するテンプレートフィールドを短縮してください。 |
| 406 | ft.InvalidParameter | テンプレート構造が無効です。たとえば、main がオブジェクトではない、charts、vars、groups が配列ではない、またはチャートクエリ構造が無効です | パラメータ{}が無効です |
エラーで示されたフィールドパスに従ってテンプレートを修正してください。本バージョンのエクスポート API が返す完全なテンプレートを優先して使用してください。 |