削除¶
POST /api/v1/account/delete
概要¶
アカウントを一括で論理削除し、そのメンバーやロールなどの関連付けをクリーンアップします。
呼び出し前の確認と使用手順¶
w 権限を持つ External 資格情報が必要です。まずアカウント一覧から、uuid、ニックネーム、直接関連付けられたワークスペースを項目ごとに確認します。対象アカウントのいずれかがアクティブなワークスペースの Owner ロールをまだ持っている場合、バッチ全体が削除前に失敗します。所有権を移譲してから再試行してください。事前チェックに合格すると、アカウントおよびワークスペースメンバー、ロール、メンバーグループ、バックエンドグループ、カスタムワークスペース設定、リソース関連付けを論理削除し、アカウントキャッシュ、ログイン Token をクリーンアップし、ワークスペースメンバー権限キャッシュを非同期で更新します。削除は一時的な無効化ではありません。一時的にログインを禁止する必要がある場合は、有効化/無効化を使用してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| accountUUIDs[*] | string | 単一の対象アカウント UUID 文字列です。ワークスペース UUID ではありません。 例: acnt_example001取得または入力方法: アカウント一覧の content.data[].uuid から項目ごとに取得します。 |
|
| accountUUIDs | array | Y | 対象アカウント UUID の配列です。クライアントはまず範囲を確認し、空でない文字列リストを送信する必要があります。空の配列はすべてのアカウントに一括で影響することはなく、不明または削除済みの UUID は無視されます。 null の許可: False 例: ["acnt_example001"]取得または入力方法: アカウント一覧の content.data[].uuid から項目ごとに取得します。wksp_ ワークスペース UUID を入力しないでください。 |
パラメータの補足説明¶
サイトレベルの External API 資格情報を使用します。認証方式はExternal API 署名認証を参照してください。以下の例では署名バージョン v20240417 を使用します。署名パス、Query エンコーディング、および元のリクエスト本文は、実際に送信する内容と完全に一致している必要があります。返されるアカウント情報には password フィールドは含まれません。mfaSecret は固定のマスクのみであり、ログインに使用できるキーではありません。この API にはロールバック/復元のエントリポイントはありません。異常時には、データベーストランザクションと実行済みのキャッシュ、Token のクリーンアップが同期的にロールバックされるとは限りません。500 のみに基づいてアカウントが完全に変更されていないと判断せず、項目ごとに再クエリして確認してから再試行してください。
リクエスト例¶
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/account/delete'
query = {}
data = {'accountUUIDs': ['acnt_example001']}
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、Content-Type は application/json、共通レスポンスエンベロープです。業務データは content にあります。External API は declaration を自動的に追加せず、リストのページネーションは content.pageInfo に保持されます。
| フィールド | 型 | 説明 |
|---|---|---|
| content | boolean | 成功時は true で、アカウントごとの結果は提供されません。空の配列では削除は行われず、不明または削除済みの UUID は無視されます。 |
| content.{accountUUID} | オブジェクト配列 | ExistsOwnerRole で失敗した場合のみ: クエリされた各アカウント UUID について、その Owner ワークスペースのリストを返します。Owner でないアカウントのリストは空になる場合があります。 |
| content.{accountUUID}[].uuid | string | Owner を移譲する必要があるワークスペース UUID。 |
| content.{accountUUID}[].name | string | そのワークスペース名。 |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては、共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落しているか、フィールド値が宣言された検証条件に違反しています | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | リクエスト本文 JSON のトップレベルがオブジェクトではありません | 一部の json ファイル形式エラー | JSON オブジェクトを使用し、配列、文字列、または null をトップレベルとして送信しないでください。 |
| 400 | ft.ExistsOwnerRole | 対象アカウントのいずれかに直接関連付けられたアクティブなワークスペースに Owner ロールが存在します | 所有者ロールが存在します。先にその権限を移譲する必要があります | エラー content 内のワークスペースリストを読み取り、対応するワークスペースの所有権を先に移譲してから、アカウントを再確認して送信してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、非同期タスクの投入、または明示的に処理されていないフィールドの異常 | 内部エラー | traceId を保存して管理者に連絡してください。書き込みリクエストでは、まずアカウントの現状を再クエリし、確認してから再試行を判断してください。500 を直接「未適用」と見なすことはできません。 |
Owner 事前チェック失敗時のレスポンス例(HTTP 400、バッチではまだアカウントを削除していません):