コンテンツにスキップ

カスタムレベルの変更



POST /api/v1/incidents/level/{incidents_level_uuid}/modify

概要

現在のワークスペースにおけるカスタムインシデントレベルの名前、色、説明を変更します。

呼び出し前の注意事項と使用手順

Key には incidents.incidentsLevelManage が必要で、現在の Key が属するワークスペースにのみ適用されます。このモジュールは Issue レベル API と基盤となるレベルおよびデフォルトレベルの設定を共有しているため、変更はインシデント/Issue レベルの選択に同時に影響する可能性があります。本モジュール内だけに独立したコピーを作成するものではありません。バックエンドでグローバルレベルが有効になっている場合、実際に有効なレベルの選択はグローバル設定が優先されて決定されることがあります。本ワークスペースの管理リストには引き続きデフォルト項目とワークスペースのカスタム項目のみが表示され、バックエンドのグローバルレベルは含まれません。管理者は有効となる基準を確認したうえで変更し、管理リストのすべての項目を利用可能なレベルと見なさないでください。

実際に更新されるのは name/color/description のみです。省略した項目は保持され、description を空文字列にするとクリアされます。extend は現在無視されます。{} を渡した場合でも更新時刻は変更されます。変更されるのはレベル設定のみで、過去のインシデントの level UUID を一括で書き換えたり、通知を再送したりしません。過去の画面表示では、このレベルに基づいて名前/色が再解決される場合があります。名前を変更する際は、同一ワークスペース内の有効なカスタムレベルで重複がないか確認します。確認用に追加で old_name を返しますが、すべての旧フィールドのスナップショットは返しません。

パスパラメータ

パラメータ名 型 必須 説明
incidents_level_uuid string Y 現在のワークスペースのカスタムレベル UUID。system_level_0 などのデフォルトレベルやバックエンドのグローバルレベルは指定できません。
例: issl_example
取得・入力方法: インシデントレベル一覧 の isDefault=false の項目から uuid を取得します。

リクエストヘッダー

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

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

パラメータ名 型 必須 説明
color string 作成時は必須、変更時は省略可能です。文字列としてのみ宣言され、色形式は検証されません。データベースは128文字です。有効な16進数カラーコードの使用を推奨します。
null 許可: False
例: #3F94DC
取得・入力方法: 顧客インターフェースの配色に合わせて入力し、#RRGGBB を推奨します。
description string オプションの文字列です。作成時に省略すると空文字列、変更時に省略すると保持、空文字列はクリアとなり、null は受け付けません。データベースは1024文字のため、呼び出し側で制限してください。
null 許可: False
例: 局部功能受影响
取得・入力方法: 業務責任者がレベルの判定基準を記入します。
extend json 作成時はオブジェクトまたは null のみを受け付け、省略時はデフォルト {} です。配列や文字列などは、宣言による検証で先に 406 として拒否されます。変更ルートでは宣言されていますが、検証を通過したオブジェクトまたは null はコントローラーで無視されるため、旧 extend は変更されず、{} でクリアすることもできません。
null 許可: True
例: {}
取得・入力方法: 作成時に保存する JSON 業務拡張を入力します。
name string 作成時は必須、変更時は省略可能です。同一ワークスペース内の有効なカスタムレベルで名前を重複させることはできません。宣言は最大256文字、データベースは128文字で、1~128文字を推奨します。現在は非空を強制していません。
null 許可: False
最大長: 256
例: P3-轻微
取得・入力方法: 業務上の重大度に応じて識別しやすい名前を設定します。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/incidents/level/issl_example/modify' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"color":"#6C7AEB","description":"更新后的判定说明"}'

レスポンス

HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。

フィールド 型 説明
content.id integer または null データベース行 ID。業務上の特定には uuid を使用し、送信前のスナップショットでは null になる場合があります。
content.uuid string このリソースの UUID。
content.status integer データベース状態。0 は有効、3 は削除です。インシデントの業務状態 incidentsStatus とは異なります。
content.creator string 作成主体。API Key の場合は通常 wsak_リソースUUID です。
content.updator string 最終更新主体。未更新の場合は空になることがあります。
content.createAt integer Unix 秒の作成日時。
content.updateAt integer Unix 秒の最終更新日時。
content.deleteAt integer Unix 秒の削除日時。未削除の場合は -1 です。
content.workspaceUUID string レベルが属するワークスペース。
content.name string カスタムレベル名。
content.color string 色の表示値。通常は #RRGGBB です。サーバー側で色形式が検証されることを保証するものではありません。
content.description string レベルの説明。
content.extend JSON または null 作成時に保存される拡張。省略時は {} で、明示的な null も保存できます。変更エントリでは現在このフィールドは無視されます。
content.extend.自定义字段 JSON 呼び出し側が保存する動的な業務拡張であり、追加の制御パラメータではありません。
content.isManage boolean 本ワークスペースで作成された場合は false です。バックエンドのグローバルレベルは本モジュールでは変更されません。
content.old_name string 今回の変更前の名前。名前が変更されていない場合も返されます。
content.declaration object 現在のワークスペースの共通宣言。
{
  "code": 200,
  "content": {
    "id": 123,
    "uuid": "issl_example",
    "status": 0,
    "creator": "wsak_example",
    "updator": "wsak_example",
    "createAt": 1785427200,
    "updateAt": 1785427260,
    "deleteAt": -1,
    "workspaceUUID": "wksp_example",
    "name": "P3-轻微",
    "color": "#6C7AEB",
    "description": "更新后的判定说明",
    "extend": {},
    "isManage": false,
    "declaration": {},
    "old_name": "P3-轻微"
  },
  "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 ファイルの形式エラー オブジェクトを送信してください。
404 ft.ObjectNotExists 現在のワークスペースで、削除されていない該当カスタムレベルが見つかりません 指定されたオブジェクトが存在しません 本ワークスペースの一覧から isDefault=false の uuid を取得してください。
406 ft.IssueLevelNameExists 変更後の名前が別の有効なカスタムレベルと重複しています レベル名は既に存在します 未使用の名前を選択してください。
500 ft.InternalServerError データベース、設定/ID 形式、または未処理のシステム例外 内部エラー 読み取りはバックオフして再試行できます。書き込みは、まず設定/レベル一覧を読み戻して保存済みか確認してから、再試行するか判断してください。

フィードバック

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