取得¶
GET /api/v1/super-account/{account_uuid}/get
概要¶
指定した未削除の管理コンソールアカウントの情報を取得します。
呼び出し前の準備と使用手順¶
r または w 権限の External 認証情報が必要です。パスの UUID は管理コンソールアカウント一覧から取得します。有効または無効のアカウントを読み取れます。削除済みまたは存在しない場合は「見つかりません」を返します。詳細はエンティティの情報であり、一覧で計算される enableMFA、creatorAccount、isSuperAdministrator は含まれません。MFA のバインド状態が必要な場合は一覧と併用してください。内部の mfaSecret フィールドを使用して独自に認証しないでください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| account_uuid | string | Y | 管理コンソールアカウントの UUID です。通常の業務アカウントの UUID ではありません。 例: mact_example001取得または入力方法: 管理コンソールアカウント一覧の content.data[].uuid から取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 秒文字列を生成します。 |
パラメータの補足説明¶
認証についてはExternal API 署名認証を参照してください。本モジュールはサイトの管理コンソールアカウントを管理します。UUID は通常 mact_ で始まり、ワークスペースの業務メンバー acnt_ でもスペース Owner でもありません。一覧/詳細は r または w 権限で使用でき、それ以外は w 権限が必要です。External は sys の身分で実行され、通常のコンソールアカウントに対する初期スーパー管理者への操作制限は適用されません。操作前に、対象アカウントとログイン可能な管理アカウントを確認してください。password と passworHistory は返されません。内部互換フィールド mfaSecret はクライアント統合向けのフィールドではありません。
リクエスト例¶
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/mact_example001/get'
query = {}
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.id | integer または null | 管理アカウントレコードの通し番号です。id=1 は初期スーパー管理者です。作成時の返却スナップショットは null になる場合があります。呼び出しには uuid を使用します。 |
| content.uuid | string | 管理アカウントの UUID です。通常は mact_ プレフィックスが付きます。 |
| content.status | integer | アカウント状態: 0 有効、2 無効、3 削除済み。一覧と詳細では 3 は除外されますが、2 は返される場合があります。 |
| content.creator | string | 作成した身分です。External では通常 sys です。 |
| content.updator | string | 最後に更新した身分です。未更新の場合は空になることがあります。 |
| content.createAt | integer | 作成日時の Unix 秒。 |
| content.deleteAt | number | 削除日時の Unix 秒です。未削除の場合は通常 -1 です。 |
| content.updateAt | number | 更新日時の Unix 秒です。一部の変更では updator のみが更新されるため、この値だけで情報が変更されたかどうかを判断することはできません。 |
| content.name | string | 表示用のニックネーム。 |
| content.username | string | 管理コンソールのログイン名。 |
| content.email | string | メールアドレスです。未設定の場合は空になることがあります。 |
| content.mobile | string | 管理アカウントの携帯電話番号を復号して表示します。未設定の場合は空です。countryCode の独立したフィールドはありません。 |
| content.role | string | 管理コンソールのロール識別子で、定義済みの用途は admin/dev です。dev は標準コンソールアカウントのパスワードログイン経路では拒否されるため、通常の読み取り専用ロールと見なすことはできません。 |
| content.resetPasswordAt | integer または null | 最後にパスワードをリセットした Unix 秒です。作成スナップショットでは null になる場合があり、永続化時の初期値は通常 -1 で、標準コンソールの初回リセット通知がトリガーされます。 |
| content.mfaSecret | string | 既存の実装が返す可能性がある内部 MFA バインド用フィールドで、業務統合には使用しません。これに基づいて認証を構築しないでください。実際の値を記録したり外部に漏らしたりしないでください。例が空であることは、既存のアカウントがすべて空であることを意味しません。 |
{
"code": 200,
"content": {
"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,
"mfaSecret": ""
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
本表は、現在の External SYS 分岐で到達可能な業務エラーのみを対象としています。通常のコンソールの実アカウントにおける自己保護エラーをそのまま流用するものではありません。データベース/キャッシュなどの一般的な 5xx はグローバルに ft.InternalServerError へ統一されます。状態や情報が保存された後に失敗する可能性があります。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータの解析に失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 404 | ft.NotFoundAccount | 詳細取得時に対象アカウントが存在しないか削除済み | 指定されたアカウントが見つかりません | 管理コンソールアカウント一覧から有効な mact_uuid を取得してください。業務アカウントの UUID は使用できません。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、監査、または未処理フィールドの異常 | 内部エラー | traceId を保持し、アカウントの現在の情報と状態を確認してください。変更/削除は保存された後に失敗する可能性があります。 |