有効化/無効化¶
POST /api/v1/super-account/set-disable
概要¶
管理バックエンドアカウントを一括で有効化または無効化します。
呼び出し前の確認と使用手順¶
まず管理バックエンドアカウント一覧で各 mact_uuid と id=1 かどうかを確認し、利用可能な管理アカウントが残っていることを確認してください。isDisable=true の場合は status=2、false の場合は status=0 を設定します。未知または削除済みのアカウントは更新しません。無効化では状態保存前にデフォルト管理 Token キャッシュモードで対象セッションをクリアし、通常のデフォルト設定では再ログインが必要です。クリア処理中の異常により、一部のセッションはすでにログアウトしている一方でアカウント状態がまだ保存されていない可能性があります。有効化しても元の Token は復元されません。この SYS エントリでは初期スーパー管理者の保護を行いません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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>取得または入力方法: 対応する SK を使用してExternal API 署名認証に従って計算します。完全に実行可能なテンプレートは以下を参照してください。 |
| X-Df-Timestamp | string | Y | サイトに設定された署名有効時間枠内である必要があり、例の時刻を再利用できません。 例: 1785427200取得または入力方法: 送信時に str(int(time.time())) を使用して現在の Unix 秒文字列を生成します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| accountUuids | commaArray | Y | 必須の CSV 文字列であり、JSON 配列ではありません。フィールド名は正確に accountUuids とします。サーバー側では直接 split し、前後の空白は除去しません。複数の UUID の間に空白を入れないでください。未知または削除済みの UUID は無視され、空文字列はどの正常なアカウントにも一致しません。 null を許可: False 例: mact_example001取得または入力方法: 管理バックエンドアカウント一覧 の content.data[].uuid から 1 つ以上の管理アカウントを取得し、半角カンマで連結します。 |
| isDisable | boolean | Y | 必須の JSON ブール値であり、文字列ではありません。 null を許可: False 選択可能な値: [True, False] 例: true取得または入力方法: 目的の状態に応じて true で無効化、false で有効化を選択します。 |
パラメータ補足説明¶
認証についてはExternal API 署名認証を参照してください。本モジュールはサイトの管理バックエンドアカウントを管理し、UUID は通常 mact_ です。ワークスペースのビジネスメンバー acnt_ でも、ワークスペース Owner でもありません。一覧/詳細では r または w 権限を使用でき、それ以外では w 権限が必要です。External は sys として実行され、通常のバックエンドアカウントに対する初期スーパー管理者への操作制限は適用されません。操作前に、対象アカウントと引き続きログイン可能な管理アカウントを確認する必要があります。インターフェースは一致件数を返しません。一致がない場合は {} を返すことがあります。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/set-disable'
query = {}
data = {'accountUuids': 'mact_example001', 'isDisable': True}
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 | object | 返却される概要であり、アカウントごとの結果ではありません。 |
| content.username | string | 任意: 一致するレコードのいずれかのログイン名で、順序は保証されません。概要を照会する際に元々削除済みのアカウントに一致する可能性もあり、これに基づいて実際の更新件数を判断できません。 |
{
"code": 200,
"content": {
"username": "api-doc-admin"
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
一致するレコードがない場合のレスポンス例:
{
"code": 200,
"content": {},
"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 オブジェクトを送信してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、監査、または未処理フィールドの異常 | 内部エラー | traceId を保持し、アカウントの現在の情報と状態を確認してください。変更/削除は保存された後に失敗する可能性があります。 |