カスタムレベルの追加¶
POST /api/v1/issue-level/add
概要¶
現在のワークスペースにカスタム Issue レベルを1件作成します。
呼び出し前の準備と使用手順¶
name と color を送信するだけで十分で、description と extend は省略できます。このワークスペース内の削除されていないカスタムレベルは最大10件で、名前はワークスペース内に既存の削除されていないカスタムレベルと重複できません。成功すると issl_ で始まる uuid を返します。プラットフォームのグローバルレベルが優先的に有効な場合、新規作成したレベルは保存済みであっても有効なレベルリストに一時的に表示されないことがあります。Issue に使用できるかどうかは有効なリストで判断してください。操作は現在の API Key が属するワークスペースで行われます。リソース識別子は同じワークスペースから取得してください。タイムアウトした場合は、まずコンソールのレベル設定で作成済みかどうかを確認してから、再試行するかどうかを判断してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作の権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| extend.自定义字段 | json | 任意の追加 JSON フィールド。 例: urgent取得または入力方法: 連携システムが業務要件に応じて命名し、フィールド型を安定に保ってください。 |
|
| color | string | Y | レベルの色。作成時に必須です。サーバー側では文字列として宣言され、色形式の列挙は制限されていません。 null 許容: False 例: #FF7931取得または入力方法: クライアントで表示できる色を選択してください。 #RRGGBB 形式の文字列を推奨します。 |
| description | string | 省略可能なレベルの説明。 null 許容: False 例: 需要当天响应取得または入力方法: 判定基準と期待する応答時間を簡潔に記述してください。1024 文字以内を推奨します。省略した場合は空文字列になります。 |
|
| extend | json | 省略可能な追加 JSON。作成時に保存されます。固定の業務サブフィールドはありません。 null 許容: True 例: {}取得または入力方法: カスタムの追加情報を保存する必要がある場合は JSON オブジェクトを渡してください。内容がない場合は省略するか {} を指定します。 |
|
| name | string | Y | レベルの名前。作成時に必須です。最大 256 文字と宣言されていますが、現在の永続化フィールドはより短いため、128 文字以内を推奨します。 null 許容: False 最大長: 256 例: 紧急处理取得または入力方法: 業務に応じて、このワークスペース内で未使用の名前を選択してください。128 文字以内を推奨します。 |
パラメータの補足説明¶
カスタムレベルの作成は、過去の Issue の level を変更せず、Issue 通知も直接送信しません。現在のルートでは名前の 256 文字という宣言と永続化容量に差異があるため、推奨長を使用することで保存失敗を減らせます。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/issue-level/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"紧急处理","color":"#FF7931","description":"需要当天响应"}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer または null | レコード番号。Issue 作成/返信のレスポンスは永続化前に構築される場合、null になることがあります。リソースの操作には uuid を使用してください。 |
| content.uuid | string | リソースの UUID。 |
| content.workspaceUUID | string | 所属ワークスペースの UUID。 |
| content.status | integer | レコード状態。0 は正常、3 は削除済み。Issue の業務ステータス statusType とは区別されます。 |
| content.creator | string | 作成した呼び出し元。API Key の識別子、アカウント、またはシステム ID の場合があります。 |
| content.updator | string | 最後に更新した主体。未設定の場合は空文字列。 |
| content.createAt | integer | 作成日時(Unix 秒)。 |
| content.updateAt | integer | 最終更新日時(Unix 秒)。未更新の場合は -1 になることがあります。 |
| content.deleteAt | integer | 削除日時(Unix 秒)。未削除の場合は -1。 |
| content.name | string | カスタムレベルの名前。 |
| content.color | string | 色文字列。 |
| content.description | string | レベルの説明。 |
| content.extend | object または null | 作成時に保存された追加 JSON オブジェクト。レベルの変更 API は現在このフィールドを変更しません。 |
| content.isManage | boolean または number | プラットフォーム管理レベルかどうか。ワークスペース側で作成したものは通常 false です。 |
| content.declaration | object または null | ワークスペースの共通宣言。content のこの階層にのみ付加されます。 |
{
"code": 200,
"content": {
"id": 201,
"uuid": "issl_example",
"workspaceUUID": "wksp_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785430800,
"updateAt": -1,
"deleteAt": -1,
"name": "紧急处理",
"description": "需要当天响应",
"color": "#FF7931",
"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 ファイルの形式エラー | JSON オブジェクトを送信してください。 |
| 406 | ft.IssueLevelCountLimit | このワークスペースに削除されていないカスタムレベルが 10 件存在 | ワークスペースのカスタムレベルがワークスペースで許容される最大数 10 件を超えています | 使用しなくなったカスタムレベルを削除してから再試行してください。 |
| 406 | ft.IssueLevelNameExists | このワークスペースに同名の削除されていないカスタムレベルが存在 | レベル名は既に存在します | 別の名前を選択してください。タイムアウトした場合は、まず作成済みかどうかを確認してください。 |
| 500 | ft.InternalServerError | レベルまたは設定の保存、監査、その他の内部処理に失敗 | 内部エラー | まず現在のレベルまたは設定を読み取って結果を確認してから再試行してください。継続的に失敗する場合は traceId を提供してください。 |