콘텐츠로 이동

활성화/비활성화



POST /api/v1/account/set-disable

개요

지정된 계정을 일괄 활성화하거나 비활성화합니다.

호출 전 및 사용 단계

w 권한의 External 자격 증명이 필요합니다. isDisable=true이면 비활성화 status=2로, false이면 정상 status=0으로 설정합니다. 비활성화 시 해당 계정의 로그인 토큰을 지우고 프로필 캐시를 정리하려고 시도한 뒤 관련 워크스페이스 알림 구성을 비동기로 새로 고칩니다. 토큰 정리에 실패하면 로그가 기록되지만 API는 여전히 성공할 수 있으므로 강제 로그아웃을 보장해야 하는 경우 관리자에게 확인을 요청하십시오. 활성화해도 기존 토큰은 복원되지 않으며 멤버는 다시 로그인해야 합니다. 알 수 없거나 이미 삭제된 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 초 문자열을 생성합니다.

Body 요청 매개변수

매개변수 이름 유형 필수 설명
accountUUIDs[*] string 개별 대상 계정 UUID 문자열이며 워크스페이스 UUID가 아닙니다.
예시: acnt_example001
확인 또는 입력 방법: 계정 목록의 content.data[].uuid에서 항목별로 가져옵니다.
accountUUIDs array Y 대상 계정 UUID 배열입니다. 클라이언트는 먼저 범위를 확인하고 비어 있지 않은 문자열 목록을 전송해야 합니다. 빈 배열은 모든 계정에 일괄 영향을 주지 않으며, 알 수 없거나 이미 삭제된 UUID는 무시됩니다.
null 허용: False
예시: ["acnt_example001"]
확인 또는 입력 방법: 계정 목록의 content.data[].uuid에서 항목별로 가져오며 wksp_ 워크스페이스 UUID를 입력하지 마십시오.
isDisable boolean Y 필수 boolean 값이며 문자열이 아닙니다. 비활성화하기 전에 계정을 계속 보존해야 하는지 확인하십시오.
null 허용: False
선택 가능한 값: [True, False]
예시: true
확인 또는 입력 방법: 대상 상태에 따라 true는 비활성화, false는 활성화를 선택합니다.

매개변수 추가 설명

사이트 수준 External API 자격 증명을 사용하며 인증 방식은 External API 서명 인증을 참조하십시오. 다음 예시는 v20240417 서명 버전을 사용하며, 서명 경로, Query 인코딩 및 원본 요청 본문은 실제 전송 내용과 완전히 일치해야 합니다. 반환되는 계정 프로필에는 password 필드가 포함되지 않으며, mfaSecret은 고정 마스크일 뿐 로그인에 사용할 수 있는 키가 아닙니다. 이 작업은 워크스페이스 멤버 및 역할 관계를 유지하며, 다시 활성화한 후에도 기존 연결은 그대로 남습니다. 성공은 API 흐름이 완료되었음만 의미하므로 목록에서 status를 확인하십시오.

요청 예시

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/set-disable'
query = {}
data = {'accountUUIDs': ['acnt_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, Content-Type은 application/json이며 통합 응답 래퍼를 사용합니다. 비즈니스 데이터는 content에 있습니다. External API는 declaration을 자동으로 추가하지 않으며 목록 페이지네이션은 content.pageInfo에 유지됩니다.

필드 유형 설명
content object 성공 시 빈 객체 {}입니다. 계정별 결과가 아니며 알 수 없는 UUID도 별도로 오류를 보고하지 않습니다.
{
  "code": 200,
  "content": {},
  "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.AgentMemberCanNotDisable isDisable=true인 비활성화 요청에서만, 배치에 source=agent이고 status가 0, 1, 2인 계정이 존재함 agent 소스 멤버는 비활성화할 수 없습니다 해당 배치에서 agent 소스 계정을 제거하고 해당 통합을 통해 상태를 관리하십시오.
500 ft.InternalServerError 데이터베이스, 캐시, 비동기 작업 전달 또는 명시적으로 처리되지 않은 필드 예외 내부 오류 traceId를 저장하고 관리자에게 문의하십시오. 쓰기 요청은 먼저 계정 현황을 다시 조회하여 확인한 후 재시도 여부를 결정하며, 500을 곧바로 미적용으로 간주해서는 안 됩니다.

문서 평가

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