一覧取得¶
GET /api/v1/role/list
概要¶
対象ワークスペースのロールをページングして一覧表示します。
呼び出し前の準備と使用手順¶
対象ワークスペースの API キーを使用して呼び出しを行います。一覧には、ワークスペースに適用されるシステム組み込みロール、管理コンソール組み込みロール、ワークスペースカスタムロールが含まれます。特定のロールを検索する場合は名前で絞り込み、安定した識別子として uuid を読み取ります。
サイトドメイン表から、所属サイトの OpenAPI アドレスを選択します。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI キー認証情報。API キーレコードの UUID ではなく、完全なキー値を使用します。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API キー管理で、このインターフェースの権限を持つキーを作成または取得します。 |
クエリリクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| search | string | 名前によるあいまい一致。省略または空白を渡した場合は名前でフィルタリングしません。 null 許可: False 例: 只读取得または入力方法: コンソールのロール管理ページに表示されるロール名、またはその一部を使用します。 |
|
| statMember | boolean | 小文字の true を渡した場合にのみメンバー数を集計し、各ロールに memberCount を追加します。デフォルトでは集計しません。 null 許可: False 例: true取得または入力方法: ロールのメンバー数を表示する必要がある場合は、URL クエリパラメータ statMember=true を設定します。 |
|
| pageSize | integer | 1 ページあたりの件数。デフォルトは 100 です。正の整数を渡してください。 null 許可: False 例: 100取得または入力方法: クライアントが必要とするページ容量に応じて整数を入力します。 |
|
| pageIndex | integer | ページ番号。デフォルトは 1 です。 null 許可: False 例: 1取得または入力方法: 1 からページごとに増やし、レスポンスのページ番号で確認します。 |
パラメータ補足¶
ワークスペースはリクエスト内の DF-API-KEY によって決定されます。
リクエスト例¶
curl --get -H "DF-API-KEY: <DF-API-KEY>" \
"https://openapi.guance.com/api/v1/role/list" \
--data-urlencode "search=只读" \
--data-urlencode "statMember=true" \
--data-urlencode "pageIndex=1"
レスポンス¶
HTTP 200、application/json。
| フィールド | 型 | 説明 |
|---|---|---|
| content.data | array<object> |
現在のページの結果。レコードがない場合は空配列です。 |
| content.data[].id | integer | ロールレコード ID。 |
| content.data[].uuid | string | ロール UUID。以降のロール詳細取得ではこのフィールドを使用します。 |
| content.data[].name | string | ロール名。 |
| content.data[].desc | string | ロールの説明。 |
| content.data[].isSystem | integer | 1 はシステム組み込みロール、0 はその他のロールを示します。 |
| content.data[].workspaceUUID | string | ロールが所属する、または適用されるワークスペース。システム組み込みロールでは空の場合があります。 |
| content.data[].builtinRoleUUID | string | 管理コンソール組み込みロールテンプレートの UUID。テンプレートがない場合は空です。 |
| content.data[].isAllWorkspace | integer | 管理コンソール組み込みロールをすべてのワークスペースに適用するかどうか。0 はいいえ、1 ははいです。 |
| content.data[].isManageBuiltinRole | boolean | 管理コンソールで定義および適用された組み込みロールかどうか。 |
| content.data[].creator | string | 作成者の識別子。 |
| content.data[].updator | string | 最終更新者の識別子。 |
| content.data[].createAt | integer | 作成日時。Unix 秒。 |
| content.data[].updateAt | integer | 最終更新日時。Unix 秒。 |
| content.data[].deleteAt | integer | 削除日時。Unix 秒。未削除の場合は -1 です。 |
| content.data[].status | integer | ロールレコードのステータス。 |
| content.data[].creatorInfo | object | 作成者情報。取得できない場合は {} です。 |
| content.data[].updatorInfo | object | 最終更新者情報。取得できない場合は {} です。 |
| content.data[].memberCount | integer | statMember=true の場合にのみ返されます。メンバー単位で重複排除され、直接付与されたメンバーとグループ経由でこのロールを取得したメンバーを含みます。 |
| pageInfo | object | ページング情報。 |
| pageInfo.pageIndex | integer | 現在のページ番号。1 から始まります。 |
| pageInfo.pageSize | integer | 1 ページあたりの件数。 |
| pageInfo.count | integer | 現在のページで返されたレコード数。 |
| pageInfo.totalCount | integer | 条件を満たすロールの総数。現在のページにレコードがない場合でも、総ページ数の計算に使用できます。 |
| content.declaration | object または null | ワークスペースの公開宣言データ。設定が空の場合は null になることがあります。 |
{
"code": 200,
"content": {
"data": [
{
"id": 101,
"uuid": "role_example",
"name": "日志只读",
"desc": "查询应用日志",
"isSystem": 0,
"workspaceUUID": "wksp_example",
"builtinRoleUUID": "",
"isAllWorkspace": 0,
"isManageBuiltinRole": false,
"status": 0,
"creatorInfo": {},
"updatorInfo": {},
"memberCount": 2
}
],
"declaration": null
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE",
"pageInfo": {
"pageIndex": 1,
"pageSize": 100,
"count": 1,
"totalCount": 1
}
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 宣言されていないクエリパラメータが渡された | メッセージに無効なパラメータが示されます。 | パラメータ表に記載されていないフィールドを削除します。 |