삭제¶
POST /api/v1/mgroup/{group_uuid}/delete
개요¶
백오피스 그룹 및 해당 계정, 워크스페이스 역할 연결을 삭제합니다.
호출 전 확인 및 사용 단계¶
먼저 백오피스 그룹 목록에서 두 가지 펼침 보기를 열어 모든 구성원과 워크스페이스 권한을 확인하고, 해당 계정이 더 이상 이 그룹에 의존하여 관련 워크스페이스에 액세스하지 않는지 확인합니다. 요청에는 Body가 없습니다. group_uuid에 해당하는 활성 백오피스 그룹 하나를 삭제합니다. 이 작업은 그룹 및 활성 구성원/워크스페이스 역할 연결을 소프트 삭제하고 관련 워크스페이스 권한 캐시를 비동기로 새로 고칩니다. 계정이나 워크스페이스는 삭제하지 않으며 수집 Token도 직접 무효화하지 않습니다. 계정이 다른 직접 관계/그룹을 통해 획득한 권한은 별도로 확인해야 합니다. 이미 존재하지 않는 그룹을 반복 삭제하면 404를 반환하며, 이는 멱등 성공이 아닙니다. 그룹/관계 상태가 먼저 커밋된 후 권한 캐시 새로 고침이 전달됩니다. HTTP 200은 모든 후속 요청이 새 권한을 즉시 사용했음을 보장하지 않으며, 전달 또는 감사 실패의 500도 주체 저장 이후에 발생할 수 있습니다. 먼저 목록을 페이지 단위로 읽고 uuid로 대상을 찾습니다. 수정 시에는 전체 members/refWorkspaces를 펼쳐 확인해야 하며, 삭제 시에는 대상이 더 이상 활성 목록에 없는지 확인한 후 재시도 여부를 결정합니다. 새로 고침 대상 목록이 비어 있으면 공유 작업은 모든 활성 워크스페이스를 새로 고칩니다. 이를 현재 그룹만 새로 고치는 것으로 이해해서는 안 됩니다.
경로 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| group_uuid | string | Y | 활성 백오피스 그룹 UUID이며, 단일 워크스페이스의 group_ 팀 UUID가 아닙니다. 예: mgroup_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 초 문자열을 생성합니다. |
파라미터 추가 설명¶
사이트 수준 External API AK/SK를 사용하며, 서명 방식은 External API 서명 인증을 참조합니다. 백오피스 그룹 mgroup_는 여러 워크스페이스에 연결하고 상속 역할을 부여할 수 있으며, 단일 워크스페이스 내의 group_ 팀과 동일한 유형의 객체가 아닙니다. 쓰기 요청에는 w 권한이 필요하며, 목록은 r 또는 w를 사용할 수 있습니다. 그룹과 연결은 먼저 커밋되며, 이후 캐시 작업 전달 또는 감사 실패 시에도 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/mgroup/mgroup_example001/delete'
query = {}
data = None
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 공통 래퍼이며 비즈니스 데이터는 content에 있습니다. External은 declaration에 자동으로 추가되지 않으며, 목록 페이지네이션은 content.pageInfo에 있습니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | boolean | 삭제 프로세스가 성공하면 true이며, 제거된 구성원 또는 워크스페이스 수는 반환하지 않습니다. |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조합니다.
표에는 확인된 요청 및 비즈니스 오류가 나열되어 있습니다. 일반 내부 예외는 최종적으로 500 ft.InternalServerError가 됩니다. 그룹/관계가 이미 커밋되었지만 이후 캐시 또는 감사가 실패했을 수 있으므로 먼저 현재 상태를 읽어야 하며, 오류만으로 적용되지 않았다고 추론해서는 안 됩니다.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 유형 및 값을 확인합니다. |
| 404 | ft.MGroupNoExists | 그룹 UUID가 존재하지 않거나 그룹이 이미 삭제됨 | 그룹이 존재하지 않음 | 백오피스 그룹 목록에서 활성 mgroup_ 레코드 uuid를 가져옵니다. |
| 500 | ft.InternalServerError | 데이터베이스, 비동기 캐시 새로 고침 전달, 감사 또는 처리되지 않은 필드 예외 | 내부 오류 | traceId를 저장하고 목록에서 그룹/구성원/역할의 현재 상태를 확인합니다. 데이터가 이미 커밋되었을 수 있으므로 무작정 반복 생성하거나 전체를 덮어쓰지 마십시오. |