콘텐츠로 이동

삭제



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"
}

문서 평가

이 페이지가 도움이 되었나요?