一覧取得¶
GET /api/v1/workspace/{workspace_uuid}/member/list
概要¶
ワークスペースの有効メンバーとその直接ロールおよび継承ロールをページングして照会します。
呼び出し前と使用手順¶
r または w 権限の External 認証情報が必要です。一覧には直接メンバーとバックエンドグループから継承されたメンバーが含まれます。返されるのは status=0 のアカウントのみで、nameSpace は空であるか、そのワークスペースに設定済みの SSO 名前空間内である必要があります。アカウントが無効化済み、削除済み、または SSO 名前空間が一致しない場合は表示されません。見つからないという理由だけで関係がすでに存在しないと判断しないでください。返されるロールには、roles の直接ロール、mgroups のバックエンドグループ継承ロール、member_group のチーム継承ロールが含まれます。継承ロールは直接ロールを置き換える対象ではありません。アカウントのグローバル name の昇順で並び、参加時刻順ではありません。search はグローバルニックネーム、メールアドレス、ワークスペースニックネームに同時に一致しますが、この返却構造には個別の acntWsNickname フィールドはありません。ページング情報は content.pageInfo 内にあります。結果がない場合は data=[] で、誤ったワークスペース UUID でも空のリストが返る可能性があるため、先に対象ワークスペースを確認してください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| workspace_uuid | string | Y | 対象ワークスペースの UUID。まず有効状態とサイトを確認してください。 例: wksp_example001取得または入力方法: ワークスペース一覧 の content.data[].uuid から取得し、ワークスペース名を確認します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 元のパスとリクエストボディの署名バージョンです。省略したまま本ページのアルゴリズムを継続使用することはできません。 例: v20240417取得または入力方法: 本ページの例ではこの固定バージョンを使用しており、例の署名アルゴリズムと組み合わせて使用します。 |
|
| X-Df-Access-Key | string | Y | 読み取り API では r または w 認証情報を使用でき、書き込み API には w 認証情報が必要です。 例: <external-access-key>取得または入力方法: サイト管理者が割り当てた External API AK を使用します。ワークスペースの OpenAPI Key は使用できません。 |
| X-Df-Nonce | string | Y | 一時的なシリアル番号です。失敗して再送する場合も新しい値を生成し、署名を再計算します。 例: 97d275ee9f774315a7885ba7347acbd9取得または入力方法: リクエストごとに uuid.uuid4().hex を再生成します。 |
| X-Df-Signature | string | Y | 大文字化したメソッド、nonce、元の完全なパス、timestamp、元の UTF-8 リクエストボディをスペースで連結し、HMAC-SHA256 を適用して hex ダイジェストを取得します。 例: <hmac-sha256-hex>取得または入力方法: External API 署名認証に従い、対応する SK を使用して計算します。完全な実行可能テンプレートは以下を参照してください。 |
| X-Df-Timestamp | string | Y | サイトに設定された署名有効時間枠内である必要があり、例の時刻を再利用できません。 例: 1785427200取得または入力方法: 送信時に str(int(time.time())) を使用して現在の Unix 秒文字列を生成します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| pageIndex | integer | 任意。デフォルト 1、最小 1。 null を許可: False $minValue: 1 例: 1取得または入力方法: 1 から開始し、content.pageInfo と組み合わせて後続ページを順に読み取ります。 |
|
| pageSize | integer | 任意。デフォルト 10、最大 100。 null を許可: False $maxValue: 100 $minValue: 1 例: 10取得または入力方法: クライアント表示に合わせて 1~100 を選択します。 |
|
| search | string | 任意。前後の空白を除去したうえで部分一致検索を行います。省略または空白の場合はフィルタしません。username は検索しません。 null を許可: False 例: 示例成员取得または入力方法: メンバーのグローバルニックネーム、メールアドレス、またはワークスペースニックネームのキーワードを入力します。 |
パラメータ補足説明¶
認証についてはExternal API 署名認証を参照してください。本ページの例では v20240417 を使用し、元の完全なパス、Query、リクエストボディの署名アルゴリズムに対応しています。このモジュールは指定ワークスペースのメンバー関係またはロールを操作し、アカウント自体は作成しません。書き込みリクエストが失敗した場合は、まずメンバーとロールの現状を確認してから再試行するかどうかを判断してください。メンバー一覧には password、mobile、mfaSecret フィールドは含まれません。オンコール連絡情報は独立した返却フィールドです。この一覧をサイトの全アカウント一覧として扱わないでください。
リクエスト例¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 対象サイトのアドレスおよび管理者が割り当てた External API AK/SK に置き換えます。
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'GET'
path = '/api/v1/workspace/wksp_example001/member/list'
query = {'search': '示例成员', 'pageIndex': 1, 'pageSize': 10}
data = None
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
レスポンス¶
HTTP 200、application/json の共通エンベロープで、業務データは content にあります。External は declaration に自動的に追加されず、一覧のページネーションは content.pageInfo を保持します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.data | オブジェクト配列 | 現在のページの有効メンバー。結果がない場合は空配列です。 |
| content.data[].id | integer | サイト内のアカウントレコード連番。情報としてのみ返却され、他の API を呼び出す場合は uuid を使用します。 |
| content.data[].uuid | string | アカウント UUID。後続の照会、変更、無効化、削除ではこのフィールドを使用します。 |
| content.data[].status | integer | この一覧では status=0 の有効アカウントのみを返します。 |
| content.data[].creator | string | 作成者の識別子。External による作成では通常 SYS です。 |
| content.data[].updator | string | 最終更新者の識別子。まだ更新がない場合は空になることがあります。 |
| content.data[].createAt | number | 作成時刻(Unix 秒)。 |
| content.data[].updateAt | number | 更新時刻(Unix 秒)。更新時刻がない場合は -1 になることがあります。 |
| content.data[].deleteAt | number | 状態操作時刻のフィールドで、初期値は通常 -1 です。有効化/無効化でもこの値が書き込まれるため、これのみで削除を判断せず、status を使用してください。 |
| content.data[].name | string | 表示ニックネーム。 |
| content.data[].username | string | ログインアカウント名。サードパーティアカウントでは空の場合、または他のアカウントと重複する場合があります。 |
| content.data[].email | string | アカウントの連絡先メールアドレス。作成時に空で、username がメール形式の場合は username で補完されます。 |
| content.data[].countryCode | string | 電話番号の国/地域コードを示す数字のみの文字列(例: 86)。未設定の場合は空文字列です。 |
| content.data[].exterId | string | サードパーティ ID システムの一意 ID。ローカルアカウントでは通常空です。 |
| content.data[].extend | オブジェクトまたは null | アカウントの既存拡張情報。user_icon のアバターアドレスを含む場合があります。本 API は読み取りのみで、メンバー関係のパラメータからは更新しません。 |
| content.data[].extend.user_icon | string | 任意のアバター URL または静的リソースファイル名。過去の情報を読み取る際に現れることがあり、本ページの書き込み可能なパラメータではありません。 |
| content.data[].source | string | ID ソース識別子。例: local、unknown、oidc、ldap。agent などの過去の内部ソースが存在する場合もあります。 |
| content.data[].nameSpace | string | ID 名前空間。External による作成ではデフォルトで空です。本モジュールの公開パラメータからは設定できません。 |
| content.data[].isUsed | integer または boolean | アカウントが使用済みかどうかのフラグ。 |
| content.data[].agreeTerms | integer | 規約同意フラグ。 |
| content.data[].canaryPublic | boolean | カナリアフラグ。 |
| content.data[].enableMFA | boolean | MFA を有効にするかどうか。 |
| content.data[].language | string | 言語識別子。zh、en、zh-hant、id、ja、ko。 |
| content.data[].tokenHoldTime | integer | アカウントの無操作セッション保持時間(秒)。新しいアカウントはサイトのセキュアセッション設定に従って初期化され、例の値に固定されるとは限りません。 |
| content.data[].tokenMaxValidDuration | integer | アカウントセッションの最大有効期間(秒)。新しいアカウントはサイトのセキュアセッション設定に従って初期化されます。 |
| content.data[].timezone | string | タイムゾーン識別子。未設定の場合は空です。 |
| content.data[].attributes | object | SSO 同期属性の KV オブジェクト。後続の SSO ログインによって上書きされる可能性があります。キーと値は連携先の取り決めに依存します。 |
| content.data[].attributes.{属性名} | 任意の JSON 値 | カスタム属性値。文字列の使用を推奨します。例: 部门=研发部。 |
| content.data[].customAttributes | object | 業務側で維持する属性 KV オブジェクト。 |
| content.data[].customAttributes.{属性名} | 任意の JSON 値 | 業務独自の値。文字列の使用を推奨します。例: costCenter=CC-1001。 |
| content.data[].statusPageSubs | integer | ステータスページ購読フラグ。 |
| content.data[].defaultWorkspace | string | アカウントのデフォルトワークスペース UUID。未設定の場合は空です。 |
| content.data[].brandKey | string | アカウントの現在のブランド識別子。サイトで許可されているブランドセットによって決まります。 |
| content.data[].scheduleMobile | string | シフト専用の携帯電話番号(ローカル番号)。未設定の場合は空です。 |
| content.data[].scheduleEmail | string | シフト専用メールアドレス。未設定の場合は空です。 |
| content.data[].ifScheduleMobileEnable | boolean | シフト用携帯電話番号を有効にするかどうか。 |
| content.data[].ifScheduleEmailEnable | boolean | シフト用メールアドレスを有効にするかどうか。 |
| content.data[].accountStatus | string | アカウントの追加状態識別子。未設定の場合は空です。 |
| content.data[].roles | オブジェクト配列 | このワークスペースにおけるアカウントの直接ロール概要。継承ロールはそれぞれ mgroups/member_group 内にあります。 |
| content.data[].roles[].uuid | string | ロール UUID または組み込みロール識別子。 |
| content.data[].roles[].name | string | ロール表示名。 |
| content.data[].enablePersonalAPIKey | integer | 個人 API Key を許可するかどうか。1 は許可、0 は不許可。Owner/管理者ロールとカスタム設定に基づいて計算され、継承ロールを含みます。 |
| content.data[].mgroups | オブジェクト配列 | 管理バックエンドグループによって付与されたワークスペースロール。 |
| content.data[].mgroups[].uuid | string | バックエンドグループ UUID。通常は mgroup_ プレフィックスです。 |
| content.data[].mgroups[].name | string | バックエンドグループ名。 |
| content.data[].mgroups[].roles | オブジェクト配列 | このバックエンドグループを通じて継承されたロール。 |
| content.data[].mgroups[].roles[].uuid | string | ロール UUID または組み込みロール識別子。 |
| content.data[].mgroups[].roles[].name | string | ロール表示名。 |
| content.data[].member_group | オブジェクト配列 | アカウントが所属するこのワークスペースのチームおよびチーム関連ロール。 |
| content.data[].member_group[].uuid | string | ワークスペースチーム UUID。通常は group_ プレフィックスです。 |
| content.data[].member_group[].name | string | チーム名。 |
| content.data[].member_group[].roles | オブジェクト配列 | このチームを通じて継承されたロール概要。 |
| content.data[].member_group[].roles[].uuid | string | ロール UUID または組み込みロール識別子。 |
| content.data[].member_group[].roles[].name | string | ロール表示名。 |
| content.data[].userType | string | nameSpace が空でない場合は saml、それ以外は common です。このフィールドは source と等しくなく、すべてのサードパーティアカウント種別の判定にも使用できません。 |
| content.data[].userIconUrl | string または null | アバター URL。アバターがない場合は null です。 |
| content.pageInfo.pageIndex | integer | 現在のページ番号。 |
| content.pageInfo.pageSize | integer | 1 ページあたりの件数。 |
| content.pageInfo.count | integer | 本ページで選択された件数。 |
| content.pageInfo.totalCount | integer | フィルタ条件を満たす総件数。 |
{
"code": 200,
"content": {
"data": [
{
"id": 1001,
"uuid": "acnt_example001",
"status": 0,
"creator": "SYS",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例成员",
"username": "xxx@guance.com",
"email": "xxx@guance.com",
"countryCode": "",
"exterId": "",
"extend": null,
"source": "local",
"nameSpace": "",
"isUsed": 0,
"agreeTerms": 0,
"canaryPublic": false,
"enableMFA": false,
"language": "zh",
"tokenHoldTime": 86400,
"tokenMaxValidDuration": 604800,
"timezone": "",
"attributes": {
"部门": "研发部"
},
"customAttributes": {
"costCenter": "CC-1001"
},
"statusPageSubs": 0,
"defaultWorkspace": "",
"brandKey": "guance",
"scheduleMobile": "",
"scheduleEmail": "",
"ifScheduleMobileEnable": false,
"ifScheduleEmailEnable": false,
"accountStatus": "",
"roles": [
{
"uuid": "general",
"name": "普通成员"
}
],
"enablePersonalAPIKey": 0,
"mgroups": [],
"member_group": [],
"userType": "common",
"userIconUrl": null
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 10,
"count": 1,
"totalCount": 1
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
一致するメンバーがない場合:
{
"code": 200,
"content": {
"data": [],
"pageInfo": {
"pageIndex": 1,
"pageSize": 10,
"count": 0,
"totalCount": 0
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
以下の表は確認済みの業務エラーおよびリクエストエラーです。通常のデータベース/ダウンストリームの 5xx または未処理例外はグローバルに ft.InternalServerError としてラップされます。書き込みリクエストの失敗は部分的に反映されていないことを保証しないため、まず関係の現状を確認する必要があります。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンス説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反しています | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、旧承認タスクのキャンセル、または未処理の配列/フィールド例外 | 内部エラー | traceId を保存し、管理者に実際の関係とキャッシュを確認してもらってください。書き込み操作が部分的にコミットされている可能性があるため、盲目的に再実行しないでください。 |