カスタムレベルの変更¶
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 形式、または未処理のシステム例外 | 内部エラー | 読み取りはバックオフして再試行できます。書き込みは、まず設定/レベル一覧を読み戻して保存済みか確認してから、再試行するか判断してください。 |