コンテンツにスキップ

作成



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 を提供してください。

フィードバック

このページは役に立ちましたか?