メンバー一覧¶
GET /api/v1/workspace/members/list
概要¶
現在のワークスペースのアクティブメンバー、および直接ロール・継承ロールと個人 API Key のオン/オフ設定をページ単位で取得します。
呼び出し前の準備と使用手順¶
既定では pageIndex=1、pageSize=10 で、アカウント名の順に並びます。結果には直接メンバーと、管理コンソールのアカウントグループ経由で参加したメンバーが含まれます。ロールはそれぞれ roles、mgroups[].roles、member_group[].roles に格納されます。アカウント配列は content.data から、ページング情報はトップレベルの pageInfo から読み取ります。担当者、@メンションされたメンバー、ロール変更などの API のパラメータには uuid を使用します。メールアドレスは、これらの API で共通的に使えるアカウント ID ではありません。すべての操作は、現在の DF-API-KEY が属するワークスペースを対象とします。別のワークスペースを操作する場合は、対応する Key とサイトの Endpoint を変更してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| pageIndex | integer | ページ番号。既定値は1、最小値は1。 null を許可: False $minValue: 1 例: 1取得または入力方法: 先頭ページは1、以降はページごとに増やします。 |
|
| pageSize | integer | 1ページあたりの件数。既定値は10。 null を許可: False $maxValue: 100 $minValue: 1 例: 10取得または入力方法: 必要に応じて1から100までの整数を選択します。 |
|
| search | string | 名前、メールアドレス、ワークスペース内ニックネームであいまい検索します。 null を許可: False 例: oncall取得または入力方法: アカウント名、メールアドレス、またはこのワークスペースのニックネームに含まれる文字列を入力します。省略または空白の場合はフィルタリングしません。ニックネームは検索できますが、この公開一覧 API ではこのフィールドは固定で返されません。 |
パラメータ補足説明¶
この公開 API はアカウントとロールの情報を返し、パスワード、MFA キー、主電話番号は除外されます。フロントエンドのメンバーページにある追加フィールドをそのまま当てはめないでください。たとえば、フロントエンドの承認待ちや直近の Key 呼び出しなどの情報は、この API の固定出力ではありません。
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/workspace/members/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode pageIndex=1 \
--data-urlencode pageSize=10
レスポンス¶
HTTP 200、application/json。以下の例では、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.data | array<object> |
現在のページのメンバー。結果がない場合は [] です。 |
| content.data[].id | integer | サイトアカウントレコードの番号。他の API を呼び出すときは uuid を使用します。 |
| content.data[].uuid | string | アカウント UUID。acnt_ などのアカウント識別子です。 |
| content.data[].status | integer | サイトアカウントのステータス。この一覧ではアクティブなアカウントのみを照会します。 |
| 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[].name | string | アカウント名。 |
| content.data[].username | string | ログインユーザー名。 |
| content.data[].email | string | アカウントのメールアドレス。 |
| content.data[].countryCode | string | アカウントの電話国/地域コード。 |
| content.data[].exterId | string | アカウントの外部識別子。 |
| content.data[].source | string | アカウントのソース。たとえば agent はエージェントアカウントです。その他の値は登録元/同期元に応じて提供されます。 |
| content.data[].nameSpace | string | ID 名前空間。通常のアカウントでは空で、SSO アカウントでは対応する ID ソースの識別子です。 |
| content.data[].userType | string | nameSpace が空の場合は common、それ以外は saml。 |
| content.data[].extend | object | アカウントの拡張情報。構造はアカウントのソースによって提供されます。 |
| content.data[].extend.user_icon | string | 値がある場合のアバターリソースまたは URL。userIconUrl の生成に使用されます。 |
| content.data[].extend.其他字段 | JSON | アカウントソースで定義されたその他の拡張属性。 |
| content.data[].userIconUrl | string または null | 生成されたアバター URL。アバターがない場合は null。 |
| content.data[].isUsed | boolean または integer | アカウントがこれまでに使用されたことがあるかを示すレコードフラグ。 |
| content.data[].agreeTerms | integer | アカウントの規約同意フラグ。 |
| content.data[].canaryPublic | boolean | アカウントの公開カナリアフラグ。 |
| content.data[].enableMFA | boolean | アカウントで MFA が有効かどうか。 |
| content.data[].language | string | アカウントの言語設定。 |
| content.data[].tokenHoldTime | integer | アカウントのログインセッション保持時間(秒)。特殊な値はアカウント設定に応じて提供されます。 |
| content.data[].tokenMaxValidDuration | integer | ログインセッションの最大有効期間(秒)。特殊な値はアカウント設定に応じて提供されます。 |
| content.data[].timezone | string | アカウントのタイムゾーン。 |
| content.data[].attributes | object または array | ID ソースの属性。 |
| content.data[].attributes.自定义字段 | JSON | ID ソースで定義された属性。 |
| content.data[].customAttributes | object または array | カスタムアカウント属性。 |
| content.data[].customAttributes.自定义字段 | JSON | カスタム属性値。 |
| content.data[].statusPageSubs | integer | Status Page の購読フラグ。 |
| content.data[].defaultWorkspace | string | アカウントの既定ワークスペース識別子。 |
| 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 | array<object> |
直接関連付けられたワークスペースロールの概要。継承ロールについては mgroups と member_group を参照してください。 |
| content.data[].roles[].uuid | string | ロール UUID。 |
| content.data[].roles[].name | string | ロールの表示名。 |
| content.data[].mgroups | array<object> |
管理コンソールのアカウントグループ経由で参加/認可されたグループ。 |
| content.data[].mgroups[].uuid | string | 管理アカウントグループ UUID。 |
| content.data[].mgroups[].name | string | 管理アカウントグループ名。 |
| content.data[].mgroups[].roles | array<object> |
この管理グループがこのワークスペースで付与するロール。 |
| content.data[].mgroups[].roles[].uuid | string | ロール UUID。 |
| content.data[].mgroups[].roles[].name | string | ロールの表示名。 |
| content.data[].member_group | array<object> |
このワークスペースでアカウントが所属するチーム。 |
| content.data[].member_group[].uuid | string | チーム UUID。 |
| content.data[].member_group[].name | string | チーム名。 |
| content.data[].member_group[].roles | array<object> |
チームがこのワークスペースで付与するロールの概要。 |
| content.data[].member_group[].roles[].uuid | string | ロール UUID。 |
| content.data[].member_group[].roles[].name | string | ロールの表示名。 |
| content.data[].enablePersonalAPIKey | integer | 現在のワークスペースにおける個人 API Key の使用スイッチ。1 は有効、0 は無効です。直接ロールとグループ継承ロールを統合して計算され、owner は常に 1、wsAdmin は明示的な設定がない場合の既定値が 1、その他は既定値が 0 です。 |
| content.declaration | object または null | ワークスペースの共通宣言。各アカウントに再帰的に挿入されることはありません。 |
| pageInfo | object | トップレベルのページング情報。 |
| pageInfo.pageIndex | integer | ページ番号。 |
| pageInfo.pageSize | integer | 1ページあたりの件数。 |
| pageInfo.count | integer | 現在のページで実際に返された件数。 |
| pageInfo.totalCount | integer | 一致するアカウントの総数。 |
{
"code": 200,
"content": {
"data": [
{
"id": 101,
"uuid": "acnt_example",
"name": "值班工程师",
"username": "xxx@guance.com",
"email": "xxx@guance.com",
"status": 0,
"creator": "SYS",
"updator": "",
"createAt": 1785430800,
"updateAt": -1,
"deleteAt": -1,
"nameSpace": "",
"userType": "common",
"source": "local",
"countryCode": "",
"exterId": "",
"extend": {},
"userIconUrl": null,
"isUsed": 1,
"agreeTerms": 1,
"canaryPublic": false,
"enableMFA": false,
"language": "zh",
"tokenHoldTime": 3600,
"tokenMaxValidDuration": 86400,
"timezone": "Asia/Shanghai",
"attributes": {},
"customAttributes": {},
"statusPageSubs": 0,
"defaultWorkspace": "wksp_example",
"brandKey": "guance",
"scheduleMobile": "",
"scheduleEmail": "",
"ifScheduleMobileEnable": false,
"ifScheduleEmailEnable": false,
"accountStatus": "",
"roles": [
{
"uuid": "readOnly",
"name": "只读成员"
}
],
"mgroups": [],
"member_group": [],
"enablePersonalAPIKey": 0
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE",
"pageInfo": {
"pageIndex": 1,
"pageSize": 10,
"count": 1,
"totalCount": 1
}
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては、共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落しているか、フィールド値が宣言された検証条件に違反しています | パラメータの解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 500 | ft.InternalServerError | メンバー情報または関連ロールの読み取りに失敗しました | 内部エラー | しばらくしてから再試行してください。失敗が続く場合は traceId を提供してください。 |