変更¶
POST /api/v1/super-account/{account_uuid}/modify
概要¶
管理コンソールアカウントのプロフィール、ロール、またはパスワードを変更します。
呼び出し前および使用手順¶
w 権限の External 認証情報が必要です。まず管理コンソールアカウント詳細を使用して既存のプロフィールをバックアップしてください。省略したフィールドは保持され、password が空文字列の場合もパスワードは保持されます。mobile が空文字列の場合はクリアされます。extend/exterId は未反映の互換宣言フィールドです。業務上の紐付けには使用しないでください。削除されていないアカウントを操作できます。無効化されたアカウントも含まれます。無効化されたアカウントを変更する場合、プロフィールが先に保存され、その後キャッシュ更新時に 401 AccountDisabled がスローされる可能性があります。401 を受信した場合も、まず現在の状態を確認してください。対象が存在しない場合、この SYS 分岐は 500 を返す可能性があり、詳細取得と同様に 404 を返すことは保証できません。現在の External は、通常の管理コンソールアカウントにおける初期スーパー管理者の保護を適用しません。対象を事前に確認してください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| account_uuid | string | Y | 管理コンソールアカウントの UUID であり、通常の業務アカウントの UUID ではありません。 例: mact_example001取得または入力方法: 管理コンソールアカウント一覧 の content.data[].uuid から取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 文字以内を推奨します。null や文字列以外を渡さないでください。500 が発生する可能性があります。 null 許容: False $isEmail: True 例: xxx@guance.com取得または入力方法: 通知を受信できる有効なメールアドレス文字列を入力します。 |
||
| extend | json | 任意のオブジェクト。現在の変更ではマッピング列に保存されず、対応するフィールドも返されません。 null 許容: False 例: {}取得または入力方法: 旧宣言の互換フィールドです。現在は永続化されないため、省略を推奨します。 |
|
| exterId | string | 任意の文字列。この API を通じて外部 ID の紐付けは作成されません。null は無効です。 null 許容: False 例: legacy-id取得または入力方法: 旧宣言の互換パラメータです。現在は読み取られず、永続化もされないため、省略を推奨します。 |
|
| mobile | string | 任意。省略した場合は保持されます。countryCode の分割や番号検証は実行されません。null は無効です。 null 許容: False 例: 13800138000取得または入力方法: 新しい電話番号文字列を入力するか、空文字列でクリアします。 |
|
| name | string | 任意。省略した場合は保持されます。64 文字以内を推奨します。null は無効です。 null 許容: False 例: 示例管理员新昵称取得または入力方法: 必要に応じて表示ニックネームを更新します。 |
|
| password | string | 任意。省略または空文字列の場合はパスワードを変更しません。空でない場合は強度検証を実行し、resetPasswordAt を更新します。パスワードローテーションポリシーが有効な場合、最近の設定回数以内に使用したパスワードと重複できません。null は無効です。 null 許容: False 例: Changed!2026a取得または入力方法: 新しい強力なパスワードを入力します。パスワードを変更しない場合は省略します。 |
|
| role | string | 任意。省略した場合は保持されます。dev に設定すると、デフォルト管理 Token キャッシュのクリアを試行し、標準管理コンソールログインが拒否されます。dev を通常の読み取り専用アカウントと見なすことはできません。null は無効です。 null 許容: False 例: admin取得または入力方法: このバックエンドで定義された admin/dev のみを使用します。ワークスペースのロールではありません。 |
|
| username | string | 任意。省略した場合は保持されます。削除されていない他のアカウントのログイン名と重複できません。128 文字以内を推奨し、空文字列を渡さないでください。ログイン名がクリアされ、以降のログインに影響する可能性があります。現在の宣言では非空は強制されていません。null は無効です。 null 許容: False 例: api-doc-admin-renamed取得または入力方法: 管理コンソールアカウント詳細 から現在のログイン名を読み取り、必要に応じて重複しない新しい値に変更します。 |
パラメータの補足説明¶
認証についてはExternal API 署名認証を参照してください。本モジュールはサイトの管理コンソールアカウントを管理します。UUID は通常 mact_ です。ワークスペースの業務メンバー acnt_ ではなく、ワークスペース Owner でもありません。一覧/詳細では r または w 権限を使用できます。その他には w 権限が必要です。External は sys として実行され、通常の管理コンソールアカウントに対する初期スーパー管理者の操作制限は適用されません。操作前に、対象アカウントと引き続きログイン可能な管理アカウントを確認する必要があります。変更によりアカウントプロフィールのキャッシュが更新されます。空でない新しいパスワードはリセット時刻を更新します。role=dev は現在のデフォルト管理 Token キャッシュモードをクリアします。サイトで Token key テンプレートをカスタマイズしている場合、管理者は実際のクリア効果を確認する必要があります。
リクエスト例¶
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/mact_example001/modify'
query = {}
data = {'name': '示例管理员新昵称'}
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": "sys",
"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 | リクエストフィールドが欠落しているか、フィールド値が宣言された検証条件に違反しています | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトではありません | 一部の json ファイル形式エラー | 表に従って JSON オブジェクトを送信してください。 |
| 400 | ft.InvalidPasswordRule | 作成パスワードが空または弱いパスワードであるか、変更時に指定された空でないパスワードがルールに準拠していません | 無効なパスワードルール | 8 文字以上で、数字/大文字/小文字/特殊文字の 4 種類のうち少なくとも 3 種類を含めてください。 |
| 400 | ft.NameEamilExist | username が削除されていない他の管理アカウントによって使用されています | name/email は既に存在します | 重複しないログイン名を選択してください。この分岐では実際に username を確認しており、メールアドレスの一意性を確認しているわけではありません。 |
| 406 | ft.PasswordRepeated | パスワードローテーションポリシーが有効で、新しいパスワードが最近の設定回数以内のパスワードと重複しています | 新しいパスワードは以前の {} 回分のパスワードと同じにできません | 未使用の新しい強力なパスワードを選択してください。比較回数はサイトのセキュリティポリシーによって決まります。 |
| 401 | ft.AccountDisabled | 対象アカウントが無効化されており、プロフィール送信後のキャッシュ更新が拒否されました | 現在のユーザーは無効化されています | まず照会して変更結果を確認し、承認フローに従ってアカウントを有効化してから対応してください。直接パスワード変更を繰り返さないでください。 |
| 401 | ft.AbnormalUserOrDelete | プロフィール送信後のキャッシュ更新時にアカウントが存在しない/削除されています | 現在のユーザーが存在しない/または削除済みです | アカウントのライフサイクル状態を再確認してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、監査、または未処理フィールドの異常。対象が存在しない/削除済み、メールアドレスに null/文字列以外を渡した、または保存フィールドの長さ異常 | 内部エラー | traceId を保持し、アカウントの現在のプロフィールと状態を確認してください。変更/削除が保存された後に失敗する可能性があります。 |