コンテンツにスキップ

削除



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、バッチではまだアカウントを削除していません):

{
  "code": 400,
  "content": {
    "acnt_example001": [
      {
        "uuid": "wksp_example001",
        "name": "示例空间"
      }
    ]
  },
  "errorCode": "ft.ExistsOwnerRole",
  "message": "存在拥有者角色, 需先转移该权限",
  "success": false,
  "traceId": "TRACE-EXAMPLE"
}

フィードバック

このページは役に立ちましたか?