作成¶
POST /api/v1/super-account/create
概要¶
サイト管理バックエンドアカウントを作成します。
呼び出し前の確認と使用手順¶
External 認証情報の w 権限が必要です。まず管理バックエンドアカウント一覧でログイン名を確認し、その後 admin または dev を明確に選択して強力なパスワードを設定します。name/email/mobile は必要に応じて指定できます。ワークスペースや通常の業務アカウントは自動作成されません。新規アカウントの永続化された resetPasswordAt は通常 -1 で、標準ログイン時に初回パスワードリセットを要求される場合があります。作成は冪等なリクエストではないため、ログイン名が重複するとエラーになります。タイムアウト後は、まず作成済みかどうかを照会してください。isDisable と extend は現在有効ではないため、無効化が必要な場合は作成後に別途有効化/無効化を呼び出してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 秒文字列を生成します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| string | 任意。省略すると空で保存されます。明示的に指定する場合は有効なメールアドレスである必要があり、空文字列は形式検証で失敗します。モデル列は 64 文字なので 64 文字以下を推奨します。null や非文字列を渡さないでください。旧宣言には型チェックがないため、500 が発生する可能性があります。 null を許可: False $isEmail: True 例: xxx@guance.com取得または入力方法: 通知を受信できる有効なメールアドレス文字列を入力します。 |
||
| extend | json | 任意の JSON オブジェクト。現在の ManageAccount には対応する永続フィールドがなく、作成時に保存されず、返却もされないため、省略を推奨します。 null を許可: False 例: {}取得または入力方法: 旧宣言との互換性のみを目的としており、このフィールドで業務データを保存しません。 |
|
| isDisable | boolean | 任意のブール値。現在の作成実装ではこのフィールドは無視され、新規作成時も status=0 のままです。true で無効アカウントを作成することはできません。 null を許可: False 選択可能な値: [True, False] 例: false取得または入力方法: 無効化が必要な場合は、作成成功後に uuid を取得して有効化/無効化を呼び出します。 |
|
| mobile | string | 任意。省略すると空になります。本モジュールでは暗号化して保存するのみで、通常の業務アカウントで行う countryCode の分割/完全な番号検証は実行しません。null は不正です。 null を許可: False 例: 13800138000取得または入力方法: アカウントの携帯電話番号文字列を入力します。未設定の場合は省略するか空文字列にします。 |
|
| name | string | 任意。省略すると空文字列になります。モデル列は 64 文字なので 64 文字以下を推奨します。null は不正です。 null を許可: False 例: 示例管理员取得または入力方法: アカウントの表示ニックネームを入力します。 |
|
| password | string | Y | 必須の生文字列で、HTTPS 経由で送信されます。8 文字以上で、数字/大文字/小文字/特殊文字の 4 種類のうち少なくとも 3 種類を含む必要があります。管理バックエンド画面の RSA ラップフィールドではありません。null は不正です。 null を許可: False 例: Example!2026a取得または入力方法: 呼び出し元が安全な初期パスワードを生成し、適切な経路でアカウント本人に渡します。 |
| role | string | Y | 必須のロール識別子。定義済みの admin/dev のみを使用することを推奨します。現在の宣言では列挙が制限されておらず、他の値には安定した権限セマンティクスがありません。dev は標準の管理バックエンドアカウントのパスワードログインではログインできません。 null を許可: False 例: admin取得または入力方法: 管理バックエンドアカウントの用途に応じて admin または dev を選択し、ワークスペースのロール UUID は使用しません。 |
| username | string | Y | 必須の文字列。呼び出し元は空でないログイン名を使用する必要があります。現在の宣言では空でないことを強制していません。保存列は 128 文字なので 128 文字以下を推奨します。 null を許可: False 例: api-doc-admin取得または入力方法: 管理バックエンドアカウント一覧で既存のログイン名を確認し、未使用の新しい値を指定します。 |
パラメータ補足説明¶
認証についてはExternal API 署名認証を参照してください。本モジュールはサイト管理バックエンドアカウントを管理し、UUID は通常 mact_ です。ワークスペースの業務メンバー acnt_ でも、ワークスペース Owner でもありません。一覧/詳細では r または w 権限を使用でき、それ以外は w 権限が必要です。External は sys として実行され、通常のバックエンドアカウントに対する初期スーパー管理者の操作制限は適用されません。操作前に、対象アカウントと引き続きログイン可能な管理アカウントを確認する必要があります。作成レスポンスは flush 前のスナップショットを取得するため、id と resetPasswordAt は null になる可能性があります。永続化された情報は詳細で読み取ってください。レスポンスには password または passworHistory は含まれません。
リクエスト例¶
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 = 'POST'
path = '/api/v1/super-account/create'
query = {}
data = {'username': 'api-doc-admin', 'password': 'Example!2026a', 'name': '示例管理员', 'email': 'xxx@guance.com', 'role': 'admin'}
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": null,
"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": null,
"mfaSecret": ""
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
本表は、現在の External SYS 分岐で到達可能な業務エラーのみを保証します。通常の管理バックエンドの実アカウントの自己保護エラーをそのまま流用するものではありません。データベース/キャッシュなどの一般的な 5xx はグローバルで ft.InternalServerError に統一され、ステータスまたは情報が保存された後に失敗する可能性があります。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対応方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON 形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトではない | 一部の json ファイル形式エラー | 表の形式で JSON オブジェクトを送信してください。 |
| 400 | ft.InvalidPasswordRule | 作成パスワードが空または弱いパスワード、または変更時に指定された空でないパスワードがルールに適合しない | 無効なパスワードルール | 8 文字以上で、数字/大文字/小文字/特殊文字の 4 種類のうち少なくとも 3 種類を含めてください。 |
| 400 | ft.ObjectParmeterExists | 未削除のアカウントが同じ username を使用している | {} は既に存在します |
既存の管理アカウントを確認してください。更新が必要な場合は変更 API を使用してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、監査、または未処理フィールドの異常。メールアドレスに null/非文字列を渡した場合、またはフィールドが実際の保存長を超えた場合 | 内部エラー | traceId を保持し、アカウントの現在の情報と状態を確認してください。変更/削除は保存された後に失敗する可能性があります。 |