作成¶
POST /api/v1/role/add
概要¶
現在の API Key ワークスペースにカスタムロールを作成し、権限セットを保存します。
呼び出し前の準備と使用手順¶
まずロール名と最小限の必要な権限を確認し、その後 name と空でない keys を送信します。desc は省略できます。作成してもメンバーや API Key が自動的にそのロールにバインドされることはありません。以降のメンバー認可などの API では返却された uuid を使用します。サーバー側で重複を排除して選択可能な権限を展開し、routine.defaultAccess を自動的に追加します。作成レスポンスには最終的な権限リストが直接返されないため、ロール詳細の permissions を再度確認してください。workspace/cloudAccount/cloudBilling/rumApp などの従来のワイルドカードグループでは、新たに公開された管理者権限が旧ワイルドカードグループによって自動付与されることはないため、選択可能な範囲に応じて対応するリーフキーを明示的に送信する必要があります。タイムアウトした場合は、まず同名のロールが作成済みでないかを照会し、重複したリクエストを避けてください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作の権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| keys[*] | string | 単一の権限キーで、形式は group.permission です。現在のカスタムロールで選択可能な範囲に含まれている必要があります。group.* は許可された範囲で展開できますが、リーフ権限を明示的に送信することを推奨します。 例: anomaly.issueManage取得または入力方法: コンソールのロール管理で、現在カスタムロールから選択可能な権限を確認します。または同種のカスタムロールのロール詳細の content.permissions を参考にし、業務上の必要に応じて具体的なリーフキーを選択します。システムロール専用の権限をそのままコピーしないでください。 |
|
| desc | string | 任意の説明。作成時に省略すると空文字列になります。変更時に省略すると元の値を保持し、空文字列を送信するとクリアされます。実行時の宣言上の長さ上限は 3000 ですが、現在の保存容量はより短いため、256 文字以内に収めることを推奨します。 空文字列を許可: True null を許可: False 最大長: 3000 例: インシデントの処理を許可します。取得または入力方法: ロールの用途に応じて入力します。現在の保存容量に合わせて 256 文字以内を推奨します。 |
|
| keys | array | Y | 権限キーの文字列配列。作成時は必須です。変更時は任意と宣言されていますが、実際には少なくとも 1 つの有効な権限を指定する必要があります。更新時は旧権限を全体で置き換え、追加ではありません。 null を許可: False 例: ["anomaly.issueManage"]取得または入力方法: コンソールのロール管理で、現在カスタムロールから選択可能な権限を確認します。または同種のカスタムロールのロール詳細の content.permissions を参考にし、業務上の必要に応じて具体的なリーフキーを選択します。システムロール専用の権限をそのままコピーしないでください。 |
| name | string | Y | ロール名。作成・変更のいずれでも必須で、最大 256 文字です。 null を許可: False 最大長: 256 例: インシデント協同対応取得または入力方法: まずロール一覧で現在のワークスペースに表示されるロールを確認し、使用されていない名前を選択します。 |
パラメータ補足説明¶
作成に成功したら、ロール詳細で実際の権限を確認します。ロール一覧はワークスペースメンバー一覧などの認可フローで選択できます。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/role/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"インシデント協同対応","desc":"インシデントの処理を許可します。","keys":["anomaly.issueManage"]}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要なフィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer または null | レコード番号。作成時は送信前に構築されて返されるため null になる可能性があります。リソースの操作には uuid を使用してください。 |
| content.uuid | string | 作成された role_ ロールの UUID。 |
| content.workspaceUUID | string | 所属するワークスペース。 |
| content.name | string | ロール名。 |
| content.desc | string | ロールの説明。 |
| content.isSystem | integer | 作成されたカスタムロールは 0 です。 |
| content.builtinRoleUUID | string | 管理用の組み込みテンプレートの UUID。通常の自建ロールでは空です。 |
| content.isAllWorkspace | integer | クロスワークスペースの組み込みテンプレート適用フラグ。通常の自建ロールでは 0 です。 |
| content.status | integer | レコードの状態。作成成功時は 0 です。 |
| content.creator | string | 作成者。 |
| content.updator | string | 更新者。初期値は空文字列です。 |
| content.createAt | integer | 作成時刻(Unix 秒)。 |
| content.updateAt | integer | 更新時刻(Unix 秒)。初期値は -1 です。 |
| content.deleteAt | integer | 削除時刻(Unix 秒)。未削除の場合は -1 です。 |
| content.declaration | object または null | ワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"id": null,
"uuid": "role_example",
"workspaceUUID": "wksp_example",
"name": "インシデント協同対応",
"desc": "インシデントの処理を許可します。",
"isSystem": 0,
"builtinRoleUUID": "",
"isAllWorkspace": 0,
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785430800,
"updateAt": -1,
"deleteAt": -1,
"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.RolePermissionFormatInvalid | keys が省略されている、空である、有効な権限がない、または権限が group.permission 形式ではない | ロールの権限形式エラーです | 現在選択可能な権限キーを少なくとも 1 つ送信してください。各項目は 2 つのドットで区切ります。 |
| 406 | ft.RolePermissionInvalid | 権限グループまたはサブ権限が、現在のカスタムロールで選択可能な集合に含まれていない | ロールの権限が無効です | コンソールの選択可能範囲、または同種のカスタムロールの権限詳細から再選択してください。 |
| 400 | ft.RoleNameExists | 現在のワークスペースの表示範囲に同名のロールが存在する | ロール名{}は既に存在します |
使用されていない名前を使用してください。 |
| 500 | ft.InternalServerError | 保存、権限の更新、その他の内部処理に失敗した | 内部エラーです | まずロール詳細を照会して保存済みの名前と権限を確認してから、再試行するかを判断してください。継続的に失敗する場合は traceId を提供してください。 |