一覧取得¶
GET /api/v1/super-account/list
概要¶
サイト管理バックエンドのアカウントおよび MFA バインド状態をページングして照会します。
呼び出し前の前提と使用手順¶
削除されていないすべての管理者アカウントを、無効化済みアカウントも含めて id の降順で照会します。search はログイン名、ニックネーム、またはメールアドレスの部分一致で検索し、前後の空白を除去します。デフォルトは pageIndex=1、pageSize=20 で、最大 100 です。一覧では内部の mfaSecret を除外します。creatorAccount は解決可能な作成者のログイン名で、sys によって作成された場合は通常空です。id=1 のレコードのみ isSuperAdministrator=true を追加で返し、その他のレコードでは省略されます。enableMFA は現在の MFA 設定とバインド状況に基づいて計算されます。カスタム MFA サービスのチェックに失敗した場合はこのフィールドが省略されることがあり、false と見なすことはできません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 | デフォルトは 20、最大値は 100 です。 null の許可: False $maxValue: 100 $minValue: 1 例: 20取得または入力方法: クライアントの必要に応じて 1 から 100 の範囲で選択します。カスタム MFA チェックはアカウントごとに実行される可能性があるため、意図せず 1 回あたりの処理量を増やさないようにしてください。 |
|
| search | string | 任意。省略または空白の場合はフィルタリングしません。携帯電話番号では検索しません。 null の許可: False 例: api-doc取得または入力方法: ログイン名、ニックネーム、またはメールアドレス内のキーワードを使用します。 |
パラメータの補足説明¶
認証については External API 署名認証 を参照してください。本モジュールはサイト管理バックエンドのアカウントを管理します。UUID は通常 mact_ です。ワークスペースの業務メンバーである acnt_ ではなく、ワークスペースの Owner でもありません。一覧/詳細では r または w 権限を使用でき、それ以外には w 権限が必要です。External は sys として実行され、通常のバックエンドアカウントに対する初期スーパー管理者の操作制限は適用されません。操作前に、対象アカウントと引き続きログイン可能な管理者アカウントを確認する必要があります。カスタム MFA チェックの例外は通常アカウントごとに捕捉され、一覧全体が失敗するとは限りません。
リクエスト例¶
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/super-account/list'
query = {'search': 'api-doc', 'pageIndex': 1, 'pageSize': 20}
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 の共通エンベロープ。External は declaration を自動的に追加せず、一覧のページング情報は content.pageInfo にあります。
| フィールド | 型 | 説明 |
|---|---|---|
| content.data | オブジェクト配列 | 現在のページの削除されていない管理者アカウント。 |
| content.data[].id | integer または null | 管理者アカウントレコードの連番。id=1 は初期スーパー管理者です。作成時の返却スナップショットでは null になることがあり、呼び出し時は uuid を使用します。 |
| content.data[].uuid | string | 管理者アカウントの UUID。通常は mact_ プレフィックスです。 |
| content.data[].status | integer | アカウント状態: 0 有効、2 無効、3 削除済み。一覧と詳細では 3 を除外しますが、2 は返されることがあります。 |
| content.data[].creator | string | 作成主体。External では通常 sys です。 |
| content.data[].updator | string | 最終更新主体。更新されていない場合は空になることがあります。 |
| content.data[].createAt | integer | 作成 Unix 秒。 |
| content.data[].deleteAt | number | 削除 Unix 秒。未削除の場合は通常 -1。 |
| content.data[].updateAt | number | 更新 Unix 秒。一部の変更では updator のみが更新されるため、この値だけでプロフィールが変更されたかどうかを判断することはできません。 |
| content.data[].name | string | 表示ニックネーム。 |
| content.data[].username | string | 管理バックエンドのログイン名。 |
| content.data[].email | string | メールアドレス。未設定の場合は空になることがあります。 |
| content.data[].mobile | string | 管理者アカウントの携帯電話番号を復号して表示します。未設定の場合は空です。個別の countryCode フィールドはありません。 |
| content.data[].role | string | 管理バックエンドのロール識別子。定義済みの用途は admin/dev です。dev は標準バックエンドのアカウント/パスワードログイン経路では拒否されるため、通常の読み取り専用ロールと見なすことはできません。 |
| content.data[].resetPasswordAt | integer または null | 最終パスワードリセット Unix 秒。作成スナップショットでは null になることがあり、永続化時の初期値は通常 -1 で、標準バックエンドの初回リセット通知がトリガーされます。 |
| content.data[].creatorAccount | string | 作成者の管理者アカウントのログイン名。見つからない場合、または sys 身份の場合は通常空です。 |
| content.data[].enableMFA | boolean | MFA バインド状態。計算に失敗した場合は省略されることがあり、欠落を false と解釈すべきではありません。 |
| content.data[].isSuperAdministrator | boolean | 初期スーパー管理者 id=1 の場合のみ true を返し、その他のアカウントでは通常省略されます。 |
| content.pageInfo.pageIndex | integer | 現在のページ番号。 |
| content.pageInfo.pageSize | integer | 1 ページあたりの件数。 |
| content.pageInfo.count | integer | このページの件数。 |
| content.pageInfo.totalCount | integer | 削除されておらず、検索条件を満たす総件数。 |
{
"code": 200,
"content": {
"data": [
{
"id": 1001,
"uuid": "mact_example001",
"status": 0,
"creator": "sys",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "サンプル管理者",
"username": "api-doc-admin",
"email": "xxx@guance.com",
"mobile": "",
"role": "admin",
"resetPasswordAt": -1,
"creatorAccount": "",
"enableMFA": false
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 20,
"count": 1,
"totalCount": 1
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては 共通エラー定義 を参照してください。
本表は現在の External SYS ブランチで到達可能な業務エラーのみを対象としています。通常のバックエンドの実アカウントにおける自己保護エラーをそのまま流用するものではありません。データベース/キャッシュなどの通常の 5xx はグローバルに ft.InternalServerError に統一され、状態またはプロフィールが保存された後に失敗する可能性があります。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対応方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認します。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、監査、または未処理フィールドの例外 | 内部エラー | traceId を保持し、アカウントの現在のプロフィールと状態を確認します。変更/削除は保存された後に失敗する可能性があります。 |