変更¶
POST /api/v1/role/{role_uuid}/modify
概要¶
ワークスペースのカスタムロールの名前、任意の説明、および完全な権限セットを変更します。
呼び出し前の確認と使用手順¶
まずロール詳細を読み取って既存の権限を保存し、その後に完全なターゲットの keys と必須の name を送信します。keys は古い権限を全体置換します。省略または [] の場合は RolePermissionFormatInvalid が返り、全権限のクリアには使用できません。desc を省略すると保持され、空文字列を指定するとクリアされます。管理バックエンドアプリケーションの組み込みロールは、この API では変更できません。ワークスペースのカスタムロールに適用する場合は、既存のメンバーと API Key への権限影響を事前に確認してください。権限関係の保存後、関連アカウントと API Key の権限キャッシュのリフレッシュが呼び出され、既存のロールバインディングは削除されません。失敗時でも新しい権限が保存されている可能性があるため、まず照会してから再試行してください。サーバー側で重複を排除して選択可能な権限を展開し、routine.defaultAccess を自動的に補完します。変更成功時は true のみを返し、最終的な権限リストは直接返さないため、ロール詳細の permissions を再度照会してください。workspace/cloudAccount/cloudBilling/rumApp などの従来のワイルドカードグループについては、新たに開放された管理者権限が古いワイルドカードグループによって自動付与されることはなく、選択可能範囲に従って対応するリーフキーを明示的に送信する必要があります。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| role_uuid | string | Y | ワークスペースのカスタムロール UUID。名称や管理バックエンドの組み込みロールテンプレート UUID で代替しないでください。 例: role_example取得・入力方法: ロール一覧 の content.data[].uuid から対象のワークスペースカスタムロールを取得し、ロール詳細 で確認できます。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 | 権限キーの文字列配列。作成時は必須です。変更時は任意と宣言されていますが、実際には少なくとも 1 つの有効な権限を指定する必要があります。更新時は古い権限を全体置換し、追加ではありません。 null を許可: False 例: ["anomaly.issueManage"]取得・入力方法: コンソールのロール管理で、現在カスタムロールが選択できる権限を確認します。同種のカスタムロールのロール詳細 の content.permissions を参考に、業務に応じて具体的なリーフキーを選択することもできます。システムロール専用の権限をそのままコピーしないでください。 |
|
| name | string | Y | ロール名。作成・変更のいずれでも必須で、最大 256 文字です。 null を許可: False 最大長: 256 例: 异常协作处理取得・入力方法: まずロール一覧で現在のワークスペースで参照可能なロールを確認し、未使用の名前を選択します。 |
パラメータ補足説明¶
対象のロールが存在しない場合、現在のパスでは汎用的な内部エラーが発生することがあり、NotFoundRole が安定的に返されるわけではありません。まずロール一覧または詳細で確認してください。呼び出しに失敗した場合は、詳細と実際のアクセス結果で有効状態を確認してください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/role/role_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"异常协作处理","keys":["anomaly.issueManage"]}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | boolean | 変更フローは true を返します。最終的な権限はロール詳細から読み取ります。 |
{
"code": 200,
"content": true,
"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 を提供してください。 |
| 400 | ft.InvalidAction | 管理バックエンドアプリケーションの組み込みロールを変更しようとした | 無効な操作 | 該当する管理バックエンドでこの組み込みロールを管理するか、ワークスペースのカスタムロールを選択してください。 |