コンテンツにスキップ

一覧取得



GET /api/v1/workspace/{workspace_uuid}/role/list

概要

対象ワークスペースのロールをページングして一覧表示します。

呼び出し前の準備と使用手順

ワークスペース UUID を指定します。一覧には、ワークスペースに適用されるシステム組み込みロール、管理コンソール組み込みロール、ワークスペースカスタムロールが含まれます。特定のロールを検索する場合は名前でフィルタリングし、uuid を安定した識別子として読み取ります。

例では External API 署名バージョン v20240417 を使用します。対象サイトの External API アドレス、Access Key、Secret Key をそれぞれ DF_EXTERNAL_API_URL、DF_EXTERNAL_ACCESS_KEY、DF_EXTERNAL_SECRET_KEY に設定してください。例の ID は実際の値に置き換えてください。

ルートパラメータ

パラメータ名 型 必須 説明
workspace_uuid string Y 対象ワークスペースの UUID。
例: wksp_example
取得または入力方法: ワークスペース一覧 のレスポンスの content.data[].uuid から取得し、元の値を使用します。

リクエストヘッダー

パラメータ名 型 必須 説明
X-Df-SVersion string 署名バージョン。以下の例では v20240417 を使用します。
例: v20240417
取得または入力方法: 例のとおりに入力し、署名アルゴリズムに対応させます。
X-Df-Access-Key string Y リクエストの AK 情報
例: <access-key>
取得または入力方法: External API 管理者によって割り当てられます。
X-Df-Signature string Y 署名情報
例: <hex-signature>
取得または入力方法: Secret Key を使用し、GET、nonce、リクエストパスおよび元のクエリ文字列、タイムスタンプ、空文字列で構成されるテキストに対して HMAC-SHA256 を実行し、16 進数の結果を取得します。
X-Df-Timestamp string Y リクエスト時のタイムスタンプ
例: 1785456000
取得または入力方法: 呼び出し時の現在の Unix 秒を入力します。例: date +%s を実行します。
X-Df-Nonce string Y リクエスト時に生成する一時コード
例: b53b47e12e514616ad8cb1f17cb66dce
取得または入力方法: リクエストごとに新しいランダム値を生成します。例: uuid.uuid4().hex。

Query リクエストパラメータ

パラメータ名 型 必須 説明
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 からページごとに増やし、レスポンスのページ番号で確認します。

パラメータ補足

現在の対象サイトに割り当てられた External API 署名資格情報を使用します。

リクエスト例

import hmac
import os
import time
import uuid
from urllib.parse import urlencode
import requests

server = os.environ["DF_EXTERNAL_API_URL"].rstrip("/")
path = "/api/v1/workspace/wksp_example/role/list"
query = {'search': '只读', 'statMember': 'true', 'pageIndex': 1}
if query:
    path += "?" + urlencode(query)
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
payload = " ".join(("GET", nonce, path, timestamp, ""))
signature = hmac.digest(os.environ["DF_EXTERNAL_SECRET_KEY"].encode(), payload.encode(), "sha256").hex()
headers = {
    "X-Df-Access-Key": os.environ["DF_EXTERNAL_ACCESS_KEY"],
    "X-Df-Timestamp": timestamp,
    "X-Df-Nonce": nonce,
    "X-Df-SVersion": "v20240417",
    "X-Df-Signature": signature,
}
result = requests.get(server + path, headers=headers, timeout=15)
result.raise_for_status()
data = result.json()["content"]

レスポンス

HTTP 200、application/json。

フィールド 型 説明
content.data array<object> このページの結果。レコードがない場合は空の配列です。
content.data[].id integer ロールレコード ID。
content.data[].uuid string ロール UUID。ロール識別子を要求する他の API ではこのフィールドを使用します。
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 秒。更新されていない場合は -1 になることがあります。
content.data[].deleteAt integer 削除時刻。Unix 秒。削除されていない場合は -1 です。
content.data[].status integer ロールレコードのステータス。
content.data[].creatorInfo object 作成者情報。見つからない場合は {} です。
content.data[].updatorInfo object 最終更新者情報。見つからない場合は {} です。
content.data[].memberCount integer statMember=true の場合のみ返されます。メンバー単位で重複を排除し、直接付与されたメンバーとグループを通じてこのロールを取得したメンバーを含みます。
content.pageInfo object ページ情報。
content.pageInfo.pageIndex integer 現在のページ番号。1 から始まります。
content.pageInfo.pageSize integer 1 ページあたりの件数。
content.pageInfo.count integer 現在のページで返されたレコード数。
content.pageInfo.totalCount integer 条件を満たすロールの総数。総ページ数の計算に使用します。
{
  "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
      }
    ],
    "pageInfo": {
      "pageIndex": 1,
      "pageSize": 100,
      "count": 1,
      "totalCount": 1
    }
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

エラーレスポンス

認証、レート制限、および共通リクエストエラーについては、共通エラー定義を参照してください。

HTTP ステータス errorCode 発生条件 メッセージまたはレスポンスの説明 対処方法
406 ft.ParameterValidationFailed 宣言されていない Query パラメータが渡された場合 メッセージに無効なパラメータが示されます。 パラメータ表に記載されていないフィールドを削除します。

フィードバック

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