カスタムレベルの追加¶
POST /api/v1/incidents/level/add
概要¶
現在のワークスペースのカスタムインシデントレベルを作成します。
呼び出し前と使用手順¶
Key には incidents.incidentsLevelManage が必要で、現在の Key が所属するワークスペースのみを対象とします。このモジュールは Issue レベル API と基盤となるレベルおよびデフォルトレベルの設定を共有しているため、変更がインシデント/Issue レベルの選択に同時に影響する可能性があります。本モジュールだけに独立したコピーを作成するものではありません。バックエンドでグローバルレベルが有効な場合、実際に有効なレベルの選択はグローバル設定が優先して決定する場合があります。本ワークスペースの管理リストには引き続きデフォルト項目とワークスペースのカスタム項目のみが表示され、バックエンドのグローバルレベルは含まれません。管理者は適用範囲を確認したうえで変更し、管理リストのすべての項目を利用可能なレベルとして扱わないでください。
本ワークスペースの未削除のカスタムレベルは最大10件で、名前で重複をチェックします。4つのデフォルトレベルは含みません。作成時は issl_ レベルUUID を返し、インシデントの level などのパラメータで参照できます。冪等キーはありません。タイムアウトまたは 500 の後は、まず名前で検索し、重複作成しないでください。レベル設定のみを作成し、既存のインシデントの変更やインシデント通知のトリガーは行いません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| color | string | Y | 作成時は必須、変更時は省略可能です。文字列としてのみ宣言され、色形式は検証されません。データベースの長さは128文字です。有効な16進カラー値を使用することを推奨します。 null 許可: False 例: #3F94DC取得または入力方法: 顧客インターフェースの配色に合わせて入力し、#RRGGBB を推奨します。 |
| description | string | 任意の文字列です。作成時に省略すると空文字列になり、変更時に省略すると保持されます。空文字列を指定するとクリアされます。null は受け付けません。データベースの長さは1024文字です。呼び出し元で制限してください。 null 許可: False 例: 局部功能受影响取得または入力方法: 業務責任者がレベルの判定基準を入力します。 |
|
| extend | json | 作成時はオブジェクトまたは null のみを受け付け、省略時はデフォルトで {} になります。配列/文字列などは宣言検証によって 406 で拒否されます。変更ルートでは宣言されていますが、検証を通過したオブジェクトまたは null もコントローラーによって無視され、既存の extend は変更されません。{} でクリアすることはできません。 null 許可: True 例: {}取得または入力方法: 作成時に保存が必要な JSON 業務拡張を入力します。 |
|
| name | string | Y | 作成時は必須、変更時は省略可能です。同じワークスペース内でアクティブなカスタムレベルの名前は重複できません。宣言上は最大256文字、データベースは128文字です。1~128文字を推奨します。現在、非空は強制されていません。 null 許可: False 最大長: 256 例: P3-轻微取得または入力方法: 業務の重大度に応じて識別しやすい名前を付けます。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/incidents/level/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"P3-轻微","color":"#3F94DC","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.declaration | object | 現在のワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"id": 123,
"uuid": "issl_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"workspaceUUID": "wksp_example",
"name": "P3-轻微",
"color": "#3F94DC",
"description": "局部功能受影响",
"extend": {},
"isManage": false,
"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 ファイル形式エラー | オブジェクトを送信してください。 |
| 406 | ft.IssueLevelCountLimit | 本ワークスペースの未削除カスタムレベルが10件に達している | ワークスペースのカスタムレベルが、ワークスペースで許可される最大件数10件を超えています | まず保持する必要があるレベルを確認し、参照の移行を計画してから不要な項目を削除してください。 |
| 406 | ft.IssueLevelNameExists | 同じワークスペースのアクティブなカスタムレベルで既にこの名前が使用されている | レベル名は既に存在します | まず既存のレベルを確認してください。設定を変更する必要がある場合は、元の uuid を変更してください。 |
| 500 | ft.InternalServerError | データベース、設定/ID 形式、または未処理のシステム例外 | 内部エラー | 読み取りはバックオフして再試行できます。書き込みの場合は、まず設定/レベル一覧を読み戻して保存済みかどうかを確認してから、再試行するかどうかを決定してください。 |