コンテンツにスキップ

作成



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

フィードバック

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