コンテンツにスキップ

メンバー一覧



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

フィードバック

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