コンテンツにスキップ

一覧



GET /api/v1/account/list

概要

サイト内でまだ削除されていないフロントエンドアカウント、および直接関連付けられたワークスペースロールをページングして照会します。

呼び出し前と使用手順

r または w 権限の External 認証情報を使用します。まずニックネームまたはメールアドレスで範囲を絞り込み、その後 content.data をページごとに読み取ります。以降は content.data[].uuid を使用してアカウント詳細を呼び出します。正常および無効化済みアカウントを含み、レコード ID の降順です。フィルタ条件が固定されていても、アカウントの追加または削除によりページング結果が影響を受ける可能性があります。ページング情報は content.pageInfo 内にあります。

リクエストヘッダー

パラメータ名 型 必須 説明
X-Df-SVersion string 元のパスとリクエストボディの署名バージョン。省略したまま本ページのアルゴリズムを使用し続けることはできません。
例: v20240417
取得または入力方法: 本ページの例ではこの固定バージョンを使用し、サンプルの署名アルゴリズムと組み合わせます。
X-Df-Access-Key string Y 読み取りインターフェースでは r または w 認証情報を使用でき、書き込みインターフェースでは 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.totalCount と組み合わせてページングを停止します。
pageSize integer 1 ページあたりの件数。デフォルトは 10、最大 100。
null を許可: False
$maxValue: 100
$minValue: 1
例: 10
取得または入力方法: クライアントの必要に応じて 1 から 100 を選択します。
search string name または email の部分一致で検索します。username は検索しません。省略または空文字列の場合はフィルタしません。
null を許可: False
例: 示例成员
取得または入力方法: アカウントの name(ニックネーム)または email 内の既知のキーワードを使用します。

パラメータの補足説明

サイトレベルの External API 認証情報を使用します。認証方法はExternal API 署名認証を参照してください。以下の例では署名バージョン v20240417 を使用します。署名パス、Query エンコーディング、および元のリクエストボディは、実際の送信内容と完全に一致している必要があります。返されるアカウント情報には password フィールドは含まれません。mfaSecret は固定マスクのみであり、ログインに使用できるキーではありません。一覧の wsInfo は、直接の関連付けがない場合 null です。一覧では userIconUrl を補完しません。アバターは詳細から取得できます。

リクエスト例

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/account/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、Content-Type は application/json、統一レスポンスエンベロープです。業務データは content にあります。External API は declaration を自動的に追加しません。一覧のページング情報は content.pageInfo に保持されます。

フィールド 型 説明
content object 一覧およびページングのオブジェクト。
content.data オブジェクト配列 現在のページのアカウント。一致しない場合は空配列を返します。
content.data[].id integer サイト内のアカウントレコードの連番。情報として返されるのみで、他のインターフェースの呼び出しには uuid を使用します。
content.data[].uuid string アカウント UUID。以降の照会、変更、無効化、削除でこのフィールドを使用します。
content.data[].status integer アカウント状態: 0 は正常、2 は無効。一覧では 3(削除済み)をフィルタし、その他の履歴状態が現れる可能性があります。
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[].mobile string 携帯電話番号のローカル番号。復号して表示され、国コードは含まれません。未設定の場合は空文字列です。
content.data[].countryCode string 携帯電話番号の国/地域コードを表す数字のみの文字列。例: 86。未設定の場合は空文字列です。
content.data[].exterId string サードパーティのアイデンティティシステムにおける一意の ID。ローカルアカウントでは通常空です。
content.data[].extend object または null 既存の拡張情報。user_icon のアバターアドレスを含む場合があります。本インターフェースの作成時に渡された extend は現在保存されず、更新インターフェースでもこの入力パラメータは公開されていません。
content.data[].extend.user_icon string オプションのアバター URL または静的リソースのファイル名。履歴情報の読み取り時に現れる可能性がありますが、本ページで書き込み可能なパラメータではありません。
content.data[].source string アイデンティティソースの識別子。例: local、unknown、oidc、ldap。agent などの履歴上の内部ソースが存在する場合もあります。
content.data[].nameSpace string アイデンティティの名前空間。External による作成ではデフォルトで空です。本モジュールの公開パラメータでは設定できません。
content.data[].isUsed integer または boolean アカウントが使用済みかどうかのフラグ。
content.data[].agreeTerms integer 規約同意フラグ。
content.data[].canaryPublic boolean カナリアフラグ。
content.data[].enableMFA boolean MFA を有効にするかどうか。
content.data[].mfaSecret string 固定マスク*********************。使用可能な 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[].wsInfo オブジェクト配列または null アカウントに直接バインドされたアクティブなワークスペースおよびロール。管理バックエンドのグループによってのみ継承される権限は含まれません。
content.data[].wsInfo[].uuid string ワークスペース UUID。
content.data[].wsInfo[].name string ワークスペース名。
content.data[].wsInfo[].roles オブジェクト配列 このアカウントに直接関連付けられた有効なロール。
content.data[].wsInfo[].roles[].uuid string ロール UUID。例: owner。
content.data[].wsInfo[].roles[].name string ロール表示名。
content.data[].wsInfo[].roles[].workspaceUUID string ロール定義が属するワークスペース UUID。システム共通ロールの場合は空文字列です。
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",
        "mobile": "",
        "countryCode": "",
        "exterId": "",
        "extend": null,
        "source": "local",
        "nameSpace": "",
        "isUsed": 0,
        "agreeTerms": 0,
        "canaryPublic": false,
        "enableMFA": false,
        "mfaSecret": "*********************",
        "language": "zh",
        "tokenHoldTime": 86400,
        "tokenMaxValidDuration": 604800,
        "timezone": "",
        "attributes": {
          "部门": "研发部"
        },
        "customAttributes": {
          "costCenter": "CC-1001"
        },
        "statusPageSubs": 0,
        "defaultWorkspace": "",
        "brandKey": "guance",
        "scheduleMobile": "",
        "scheduleEmail": "",
        "ifScheduleMobileEnable": false,
        "ifScheduleEmailEnable": false,
        "accountStatus": "",
        "wsInfo": [
          {
            "uuid": "wksp_example001",
            "name": "示例空间",
            "roles": [
              {
                "uuid": "general",
                "name": "普通成员",
                "workspaceUUID": ""
              }
            ]
          }
        ]
      }
    ],
    "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"
}

エラー応答

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

HTTP ステータス errorCode トリガー条件 メッセージまたは応答説明 処理方法
406 ft.ParameterValidationFailed リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 パラメータ解析失敗 パラメータの位置、フィールド名、型、値を確認してください。
500 ft.InternalServerError データベース、キャッシュ、非同期タスクの投入、または明示的に処理されていないフィールドの異常 内部エラー traceId を保存して管理者に連絡してください。書き込みリクエストの場合は、まずアカウントの現在の状態を再取得し、確認してから再試行するかどうかを決定してください。500 をそのまま未反映と見なすことはできません。

フィードバック

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