コンテンツにスキップ

作成



POST /api/v1/viewer/add

概要

エクスプローラーを作成します。空白、テンプレート、または既存ビューのコピーに対応しています。

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

最小限のリクエストでは name のみを指定します。コピー元ビューを使用する場合は、先にエクスプローラーリストまたはダッシュボードリストでコピー元の UUID を確認してください。選択順序は、空でない sourceDashboardUUID、空でない templateInfos、templateUUID の順です。コピー元ビューが見つからない場合は空のエクスプローラーが作成されることがあるため、コピー後にレイアウトと内容を確認してください。名前が競合した場合、HTTP 200 で repeatInfo が返されるため、クライアントは新しい uuid が含まれているかを確認する必要があります。

リクエストヘッダー

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

リクエストボディのパラメータ

パラメータ名 型 必須 説明
ownerType string 互換フィールド。現在の作成ルートでは viewer に固定されています。
null 許可: False
例: viewer
取得または入力方法: 新規連携では省略できます。実際のリソースはこのエクスプローラーのエントリから作成されます。
templateUUID string 統合テンプレートの UUID。優先度は既存のコピー元ビューおよびテンプレートオブジェクトより低くなります。
null 許可: False
空文字列許可: True
最大長: 128
例: tmpl_example
取得または入力方法: 統合テンプレートの UUID を取得済みの場合に入力できます。テンプレート名しかない場合は、先に既存ビューをエクスポートし、返されたオブジェクトを使用して templateInfos を入力できます。
sourceDashboardUUID string コピーするコピー元ビューの UUID。空でない場合に優先されます。
null 許可: False
空文字列許可: True
最大長: 128
例: dsbd_source_example
取得または入力方法: エクスプローラーリストまたはダッシュボードリストから、現在のワークスペース内に既に存在するコピー元ビューを選択します。
name string Y エクスプローラー名。最大 64 文字。
null 許可: False
最大長: 64
例: 主机巡检查看器
取得または入力方法: このワークスペース内で他のエクスプローラーが使用していない名前を選択します。
desc string エクスプローラーの説明。
null 許可: False
空文字列許可: True
最大長: 2048
例: 主机巡检与状态核对
取得または入力方法: 新しいエクスプローラーの用途を入力します。省略または空の場合はテンプレートの summary をそのまま使用できます。
type string 空のエクスプローラーを作成する場合にこの型を使用します。デフォルトは CUSTOM です。テンプレートを使用する場合はその dashboardType を使用します。
null 許可: False
最大長: 32
例: CUSTOM
取得または入力方法: 通常は CUSTOM を使用します。変更する場合は詳細の content.type から取得してそのまま使用できます。
extend json 空白作成に使用する拡張情報。テンプレートを使用する場合はテンプレートの dashboardExtend を使用します。
null 許可: False
例: {}
取得または入力方法: エクスプローラー詳細の content.extend またはテンプレートの dashboardExtend から取得します。
templateInfos json エクスプローラーテンプレートの JSON オブジェクト。main でチャート、変数、グループを宣言します。
null 許可: False
空文字列許可: False
例: {"title": "主机巡检查看器", "summary": "主机巡检与状态核对", "identifier": "", "dashboardType": "CUSTOM", "dashboardExtend": {}, "dashboardMapping": [], "dashboardBindSet": [], "iconSet": {}, "main": {"type": "template", "charts": [], "vars": [], "groups": [], "chartGroupPos": []}}
取得または入力方法: 先にエクスプローラーのエクスポートを呼び出して content オブジェクトを取得します。そのまま使用するか、調整が必要なテンプレートフィールドを修正します。
isImport boolean インポート由来であることを示すマーク。リストの filter=import で使用されます。選択内容は引き続きテンプレート関連フィールドで決まります。
null 許可: False
例: false
取得または入力方法: 作成元に応じてインポートとしてマークするかを決定します。通常の作成では省略または false です。
tagNames array タグ名を入力します。空の場合はテンプレートの tagInfo をそのまま使用できます。
null 許可: False
例: ["team:ops"]
取得または入力方法: 既存のエクスプローラー詳細の content.tagInfo[].name からコピーするか、関連付けるユースケースタグを入力します。
tagNames[*] string 個々のタグ名。最大 128 文字。
null 許可: False
最大長: 128
例: team:ops
取得または入力方法: 既存のエクスプローラー詳細の content.tagInfo[].name からコピーするか、関連付けるユースケースタグを入力します。

パラメータ補足説明

テンプレートはダッシュボードテンプレートのフィールド説明と構造を共有します。この API は templateInfos を使用し、トップレベルの name が名前を決定します。ダッシュボード API のトップレベル identifier、isPublic、mapping パラメータはエクスプローラーの作成には適用されません。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/viewer/add' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"name":"主机巡检查看器","desc":"主机巡检与状态核对","type":"CUSTOM"}'

レスポンス

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 エクスプローラーリソースの所属。通常は viewer です。
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.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 名前が競合した場合に返され、作成は完了していません。name などのキーでグループ化されます。
content.repeatInfo.name array<object> 名前競合のレコード。
content.repeatInfo.name[].name string リクエスト内の名前。
content.repeatInfo.name[].importName string リクエスト内の名前。
content.repeatInfo.name[].existName string 既存のエクスプローラー名。
content.repeatInfo.name[].nameConflictUUID string 同名で一致したエクスプローラーの UUID。
content.repeatInfo.name[].conflictUUIDs array<string> 今回の競合に関係する既存エクスプローラーの UUID。
content.repeatInfo.name[].existNameIdentifier string 既存エクスプローラーの識別子。空でもかまいません。
content.repeatInfo.name[].existIdentifier string 既存の競合項目の識別子。空でもかまいません。
content.repeatInfo.name[].isCrossConflict boolean 単純な名前の重複の場合は false です。
content.repeatInfo.name[].identifier string エクスプローラー作成の競合マッチングでは識別子を送信しないため、この値は空です。
content.repeatInfo.name[].importIdentifier string リクエストのマッチング項目の識別子。この値は空です。
content.repeatInfo.name[].fileName string 関連付けられたテンプレートのファイル名。直接呼び出しでファイルがない場合は空です。
{
  "code": 200,
  "content": {
    "id": 25,
    "uuid": "dsbd_view_example",
    "name": "主机巡检查看器",
    "desc": "主机巡检与状态核对",
    "workspaceUUID": "wksp_example",
    "identifier": "",
    "ownerType": "viewer",
    "type": "CUSTOM",
    "isPublic": 1,
    "chartPos": [],
    "chartGroupPos": [],
    "iconSet": {},
    "extend": {},
    "mapping": [],
    "dashboardBindSet": [],
    "createdWay": "manual",
    "openPermissionSet": false,
    "permissionSet": [],
    "readPermissionSet": [],
    "tagInfo": [],
    "status": 0,
    "creator": "wsak_example",
    "updator": "",
    "createAt": 1785427200,
    "updateAt": -1,
    "deleteAt": -1,
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

名前が重複した場合の HTTP 200 レスポンス

{
  "code": 200,
  "content": {
    "repeatInfo": {
      "name": [
        {
          "name": "主机巡检查看器",
          "identifier": "",
          "fileName": "",
          "importName": "主机巡检查看器",
          "importIdentifier": "",
          "existName": "主机巡检查看器",
          "existIdentifier": "",
          "nameConflictUUID": "dsbd_view_example",
          "existNameIdentifier": "",
          "isCrossConflict": false,
          "conflictUUIDs": [
            "dsbd_view_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 ワークスペースで数量制限が有効になっており、上限に達している 無料プランのワークスペース {} は上限( {} 個)に達したため、新規作成できません。商用プランにアップグレードすると制限を解除できます 現在のプランとエクスプローラー数を確認してください。
400 ft.TagScopeMismatch 同名のタグが既に存在するが、スコープがユースケースと互換性がない メッセージにはタグ名、既存および対象のスコープが含まれます。 別のユースケースまたは汎用タグを使用してください。
406 ft.ExceedMaxCharacterLimit テンプレート内のチャート名またはグループ名が 256 文字を超えている、またはタグ名が 128 文字を超えている {}が最大文字数制限を超えています フィールドの長さ制限に従ってテンプレートを修正してください。
404 ft.ObjectNotExists 指定された統合テンプレート UUID が存在しない 指定されたオブジェクトが存在しません テンプレート UUID を確認するか、エクスポート可能な既存ビューまたは完全なテンプレートオブジェクトに変更してください。
406 ft.InvalidParameter テンプレート構造が無効。たとえば main がオブジェクトでない、charts、vars、groups が配列でない、またはチャートのクエリ構造が無効 パラメータ{}が無効です エラーで示されたフィールドパスに従ってテンプレートを修正してください。本バージョンのエクスポート API が返す完全なテンプレートを優先して使用してください。

フィードバック

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