一覧¶
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 をそのまま未反映と見なすことはできません。 |