콘텐츠로 이동

추가



POST /api/v1/account/add

개요

로컬 계정을 생성하거나 서드파티 exterId로 연동 계정을 생성합니다.

호출 전 및 사용 단계

w 권한의 External 자격 증명이 필요합니다. 로컬 계정은 exterId를 생략하고, 서드파티 SSO 계정은 안정적인 exterId를 제공하며 password=""를 명시합니다. source는 이 인터페이스의 공개 입력 파라미터가 아니며, 로컬은 local로 고정되고 서드파티는 기본적으로 unknown입니다. 성공 후 content.uuid를 저장합니다. 계정 생성 시 워크스페이스에 자동으로 추가되지 않으며, 워크스페이스 연결은 해당 멤버 관리 기능을 사용하세요. 타임아웃 또는 500 발생 시 먼저 계정 목록 또는 계정 상세로 생성 여부를 확인한 후 재시도하세요. 생성 시 내부적으로 계정을 먼저 제출하므로 멱등 키를 지원하지 않습니다.

요청 헤더

파라미터명 타입 필수 설명
X-Df-SVersion string 원본 경로 및 요청 본문 서명 버전이며, 생략한 후 이 페이지의 알고리즘을 계속 사용할 수 없습니다.
예시: v20240417
획득 또는 입력 방법: 이 페이지의 예시는 이 고정 버전을 사용하며, 예시 서명 알고리즘과 함께 사용됩니다.
X-Df-Access-Key string Y 읽기 인터페이스는 r 또는 w 자격 증명을 사용할 수 있고, 쓰기 인터페이스는 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 요청 파라미터

파라미터명 타입 필수 설명
attributes json 선택적 객체이며 생략 시 기본값은 {}입니다. 객체 전체가 저장되고, 값은 문자열 사용을 권장하며 이후 SSO 로그인 시 덮어쓸 수 있습니다. null일 수 없습니다.
null 허용: False
예시: {"部门": "研发部"}
획득 또는 입력 방법: SSO 매핑 규칙 또는 기업 신원 시스템에서 KV 객체를 가져오며, 필드명은 연동 양측이 약정합니다.
brandKey string 선택 사항이며, 생략 시 사이트 기본 브랜드를 사용합니다. null일 수 없으며, 모든 브랜드 사이트에서 이 값을 허용한다고 임의로 가정할 수 없습니다.
null 허용: False
예시: guance
획득 또는 입력 방법: 사이트 관리자에게 허용된 브랜드 식별자를 확인합니다.
countryCode string 문자열 국가/지역 코드입니다. 생략하고 mobile이 기존 11자리 국내 번호이면 86을 추론할 수 있으며, mobile이 비어 있으면 최종적으로 비어 있게 됩니다.
빈 문자열 허용: True
null 허용: False
예시: 1
획득 또는 입력 방법: 멤버 휴대전화 번호의 국가/지역에서 가져옵니다. 예: 중국 86, 미국 1.
customAttributes json 선택적 객체이며 생략 시 기본값은 {}입니다. 비즈니스 측에서 유지 관리하며, 값은 문자열 사용을 권장합니다. null일 수 없습니다.
null 허용: False
예시: {"costCenter": "CC-1001"}
획득 또는 입력 방법: 귀하의 비즈니스 계정 속성에서 KV 객체를 가져옵니다. 예: 비용 센터.
email string Y 필수이며, 값이 있으면 이메일 형식을 검증합니다. 빈 문자열이고 username이 이메일 형식이면 자동으로 username으로 채워집니다. null일 수 없습니다.
빈 문자열 허용: True
null 허용: False
$isEmail: True
예시: xxx@guance.com
획득 또는 입력 방법: 멤버가 알림을 수신할 수 있는 유효한 이메일을 사용하며, 이메일이 없으면 빈 문자열을 명시적으로 전달할 수 있습니다.
extend json 선택적 객체 또는 null이며, 현재 생성 구현은 이 필드를 저장하지 않지만 응답은 일반적으로 null입니다.
null 허용: True
예시: {}
획득 또는 입력 방법: 현재 선언과의 호환을 위한 것으로만 사용하며, 이 필드에 추가 정보를 저장하는 것에 의존하지 말고 비즈니스 사용자 정의 데이터는 customAttributes에 넣으세요.
exterId string 선택 사항입니다. 비어 있지 않은 값은 서드파티 생성 분기를 활성화하며 빈 네임스페이스 내에서 유일하고, 이때 source는 자동으로 unknown이 됩니다. 생략하면 local 로컬 계정을 생성합니다. 서드파티 신원을 표현하기 위해 null 또는 빈 값을 전달하지 마세요.
빈 문자열 허용: False
null 허용: False
예시: sso-user-1001
획득 또는 입력 방법: 귀하의 SSO/ID 제공자의 안정적인 사용자 ID에서 가져오며, 변경될 수 있는 닉네임은 사용할 수 없습니다.
isDisable boolean 이 선택적 불리언 필드는 현재 생성 상태를 변경하지 않으며 새 계정은 여전히 status=0입니다. isDisable=true로 비활성화된 계정을 생성하는 것에 의존하지 마세요.
null 허용: False
선택 값: [True, False]
예시: false
획득 또는 입력 방법: 새 계정을 비활성화하려면 생성 성공 후 uuid를 얻은 뒤 활성화/비활성화를 호출하세요.
language string 선택 사항이며, 생략, null 또는 빈 문자열은 모두 기본값 zh입니다. 값이 있으면 선언된 열거형 내에 있어야 합니다.
빈 문자열 허용: True
null 허용: True
선택 값: ['zh', 'en', 'zh-hant', 'id', 'ja', 'ko']
예시: zh
획득 또는 입력 방법: 멤버 선호도에 따라 zh, en, zh-hant, id, ja, ko 중 하나를 선택합니다.
mobile string 휴대전화 필드는 countryCode와 로컬 mobile 두 부분으로 구성됩니다. + 국제 번호 또는 00 접두사 국제 번호를 지원하며, 1로 시작하는 11자리 기존 국내 번호는 기본적으로 86으로 처리될 수 있습니다. 지역 코드를 제공하면 전체 번호의 유효성을 검증합니다. 생략 시 기본값은 비어 있으며, null을 전달하지 마세요.
빈 문자열 허용: False
null 허용: False
예시: 2025550123
획득 또는 입력 방법: 멤버의 실제 유효한 휴대전화 로컬 번호를 countryCode와 함께 사용하며, 구성하지 않을 때는 생략합니다.
name string Y 필수 닉네임이며, 의미 있는 비어 있지 않은 문자열을 제공합니다.
빈 문자열 허용: False
null 허용: False
예시: 示例成员
획득 또는 입력 방법: 신원 시스템의 멤버 표시 이름을 사용합니다.
password string Y 필수입니다. exterId가 없으면 최소 8자이며 숫자/대문자/소문자/특수 문자 네 가지 중 최소 세 가지를 포함해야 합니다. exterId가 있으면 해당 강도 검증을 수행하지 않으며 빈 문자열일 수 있습니다. null을 전달하지 마세요: exterId가 없으면 400 ft.InvalidPasswordRule을 반환하고, exterId가 있으면 해시 생성으로 진입하여 500 ft.InternalServerError를 반환할 수 있습니다.
빈 문자열 허용: True
null 허용: True
예시: Example!2026a
획득 또는 입력 방법: 호출자가 로컬 계정용으로 생성하여 안전하게 전달하며, 서드파티 SSO 계정은 빈 문자열을 명시적으로 입력합니다.
username string Y 필수입니다. exterId가 없으면 빈 네임스페이스 내에서 유일합니다. exterId가 있으면 중복이 허용되며 서드파티는 빈 문자열을 전달할 수 있습니다. null을 전달하지 마세요. 하위 데이터베이스가 null을 허용하지 않습니다.
빈 문자열 허용: True
null 허용: True
예시: xxx@guance.com
획득 또는 입력 방법: 로컬 계정은 사용되지 않은 로그인 이름을 사용하며 유효한 이메일을 권장합니다. 서드파티 계정은 귀하의 로그인 이름을 사용합니다.

파라미터 추가 설명

사이트 수준 External API 자격 증명을 사용하며, 인증 방식은 External API 서명 인증을 참조하세요. 다음 예시는 v20240417 서명 버전을 사용하며, 서명 경로, Query 인코딩 및 원본 요청 본문은 실제 전송과 완전히 일치해야 합니다. 반환되는 계정 정보에는 password 필드가 포함되지 않으며, mfaSecret은 고정 마스크일 뿐 로그인에 사용할 수 있는 키가 아닙니다.

서드파티 계정 최소 요청 본문 예시:

{
  "username": "",
  "password": "",
  "name": "SSO示例成员",
  "email": "",
  "exterId": "sso-user-1001"
}

로컬 비밀번호는 HTTPS 내의 원문 문자열을 사용하며, 이 인터페이스는 관리 콘솔의 RSA 비밀번호 래핑을 사용하지 않습니다.

표의 null/빈 문자열과 생략은 구분해야 합니다. 현재 문자열 타입 검증은 빈 문자열을 일괄적으로 차단하지 않으므로, 호출자는 로그인 이름, 닉네임 등에 의미 있는 비어 있지 않은 내용을 제공하고 빈 값으로 암시적 기본값을 얻는 것에 의존하지 않아야 합니다.

요청 예시

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/add'
query = {}
data = {'username': 'xxx@guance.com', 'password': 'Example!2026a', 'name': '示例成员', 'email': 'xxx@guance.com', 'language': 'zh', 'attributes': {'部门': '研发部'}, 'customAttributes': {'costCenter': 'CC-1001'}}
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.id integer 사이트 내 계정 레코드 일련번호로, 정보 반환용으로만 사용됩니다. 다른 인터페이스 호출 시에는 uuid를 사용합니다.
content.uuid string 계정 UUID이며, 이후 조회, 수정, 비활성화, 삭제 시 이 필드를 사용합니다.
content.status integer 계정 상태: 0 정상, 2 비활성화. 목록 필터에서 3은 삭제됨이며, 기타 과거 상태가 나타날 수 있습니다.
content.creator string 생성 주체 식별자이며, External 생성은 일반적으로 SYS입니다.
content.updator string 최근 수정 주체 식별자이며, 아직 수정이 없으면 비어 있을 수 있습니다.
content.createAt number 생성 시간, Unix 초.
content.updateAt number 업데이트 시간, Unix 초이며, 아직 업데이트 시간이 없으면 -1일 수 있습니다.
content.deleteAt number 상태 작업 시간 필드로 초기에는 일반적으로 -1입니다. 활성화/비활성화 시에도 이 값이 기록되므로 단독으로 삭제 여부를 판단하지 말고 status를 사용해야 합니다.
content.name string 표시 닉네임.
content.username string 로그인 계정 이름. 서드파티 계정은 비어 있거나 다른 계정과 중복될 수 있습니다.
content.email string 계정 연락 이메일이며, 생성 시 비어 있고 username이 이메일 형식이면 username으로 채워집니다.
content.mobile string 휴대전화 로컬 번호로 복호화되어 표시되며 국가 지역 코드는 포함하지 않습니다. 미설정 시 빈 문자열입니다.
content.countryCode string 휴대전화 국가/지역 코드의 순수 숫자 문자열입니다. 예: 86. 미설정 시 빈 문자열입니다.
content.exterId string 서드파티 신원 시스템의 고유 ID이며, 로컬 계정은 일반적으로 비어 있습니다.
content.extend object 또는 null 기존 확장 정보로 user_icon 아바타 주소를 포함할 수 있습니다. 이 인터페이스 생성 시 전달한 extend는 현재 저장되지 않으며, 수정 인터페이스도 이 입력 파라미터를 공개하지 않습니다.
content.extend.user_icon string 선택적 아바타 URL 또는 정적 리소스 파일명입니다. 기존 정보를 읽을 때 나타날 수 있으며, 이 페이지에서 쓸 수 있는 파라미터는 아닙니다.
content.source string 신원 출처 식별자로, 예: local, unknown, oidc, ldap. agent 등 과거 내부 출처도 존재할 수 있습니다.
content.nameSpace string 신원 네임스페이스로, External 생성 시 기본값은 비어 있습니다. 이 모듈의 공개 파라미터로는 설정할 수 없습니다.
content.isUsed integer 또는 boolean 계정 사용 여부 표시.
content.agreeTerms integer 약관 동의 표시.
content.canaryPublic boolean 카나리 표시.
content.enableMFA boolean MFA 사용 여부.
content.mfaSecret string 고정 마스크 ********************* 이며, 사용 가능한 MFA 키를 포함하지 않습니다.
content.language string 언어 식별자. zh, en, zh-hant, id, ja, ko.
content.tokenHoldTime integer 계정 무작업 세션 유지 시간(초). 새 계정은 사이트 보안 세션 설정에 따라 초기화되며, 예시 값으로 고정된다고 보장할 수 없습니다.
content.tokenMaxValidDuration integer 계정 세션 최대 유효 기간(초). 새 계정은 사이트 보안 세션 설정에 따라 초기화됩니다.
content.timezone string 시간대 식별자, 미설정 시 비어 있습니다.
content.attributes object SSO 동기화 속성 KV 객체로, 이후 SSO 로그인 시 덮어쓸 수 있습니다. 키와 값은 연동 측이 약정합니다.
content.attributes.{属性名} 임의 JSON 값 사용자 정의 속성 값으로, 문자열 사용을 권장합니다. 예: 部门=研发部.
content.customAttributes object 비즈니스 측에서 유지 관리하는 속성 KV 객체.
content.customAttributes.{属性名} 임의 JSON 값 비즈니스 사용자 정의 값으로, 문자열 사용을 권장합니다. 예: costCenter=CC-1001.
content.statusPageSubs integer 상태 페이지 구독 표시.
content.defaultWorkspace string 계정 기본 워크스페이스 UUID, 미설정 시 비어 있습니다.
content.brandKey string 계정의 현재 브랜드 식별자로, 사이트에서 허용된 브랜드 집합에 따라 결정됩니다.
content.scheduleMobile string 스케줄 전용 휴대전화 로컬 번호, 미설정 시 비어 있습니다.
content.scheduleEmail string 스케줄 전용 이메일, 미설정 시 비어 있습니다.
content.ifScheduleMobileEnable boolean 스케줄 휴대전화 사용 여부.
content.ifScheduleEmailEnable boolean 스케줄 이메일 사용 여부.
content.accountStatus string 계정 부가 상태 식별자, 미설정 시 비어 있습니다.
{
  "code": 200,
  "content": {
    "id": 1001,
    "uuid": "acnt_example001",
    "status": 0,
    "creator": "SYS",
    "updator": "",
    "createAt": 1785427200,
    "deleteAt": -1,
    "updateAt": -1,
    "name": "示例成员",
    "username": "xxx@guance.com",
    "email": "xxx@guance.com",
    "mobile": "",
    "countryCode": "",
    "exterId": "",
    "extend": null,
    "source": "local",
    "nameSpace": "",
    "isUsed": 0,
    "agreeTerms": 0,
    "canaryPublic": false,
    "enableMFA": false,
    "mfaSecret": "*********************",
    "language": "zh",
    "tokenHoldTime": 86400,
    "tokenMaxValidDuration": 604800,
    "timezone": "",
    "attributes": {
      "部门": "研发部"
    },
    "customAttributes": {
      "costCenter": "CC-1001"
    },
    "statusPageSubs": 0,
    "defaultWorkspace": "",
    "brandKey": "guance",
    "scheduleMobile": "",
    "scheduleEmail": "",
    "ifScheduleMobileEnable": false,
    "ifScheduleEmailEnable": false,
    "accountStatus": ""
  },
  "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.InvalidPasswordRule 로컬 생성 시 비밀번호가 null, 빈 문자열 또는 강도 규칙 미충족. 수정 시 제공된 비어 있지 않은 비밀번호가 강도 규칙 미충족 유효하지 않은 비밀번호 규칙 비밀번호는 최소 8자이며 숫자, 대문자, 소문자, 특수 문자 네 가지 중 최소 세 가지를 포함해야 합니다.
406 ft.InvalidBrandKey brandKey가 대상 사이트의 허용 집합에 없음 브랜드 식별자{}가 유효하지 않습니다. 사이트 관리자에게 해당 사이트에서 허용되는 브랜드 식별자를 확인한 후 원래 값을 입력하세요.
400 ft.ObjectParmeterExists 로컬 username 또는 서드파티 exterId가 삭제되지 않은 계정으로 이미 존재 <username 또는 exterId> 가 이미 존재합니다 먼저 기존 계정을 조회하고, 업데이트는 수정 인터페이스를 사용하세요. 중복 생성을 멱등 성공으로 간주해서는 안 됩니다.
429 ft.OperationTooFrequently 동일 username의 로컬 생성 잠금이 아직 해제되지 않음 작업이 너무 빈번합니다. 잠시 후 다시 시도하세요 잠시 기다린 후 먼저 기존 계정을 조회하고, 생성되지 않았음을 확인한 후 서명 요청을 다시 생성하세요.
500 ft.InternalServerError 데이터베이스, 캐시, 비동기 작업 전달 또는 명시적으로 처리되지 않은 필드 예외 내부 오류 traceId를 저장하고 관리자에게 문의하세요. 쓰기 요청은 먼저 계정 현재 상태를 다시 조회하고 확인한 후 재시도 여부를 결정해야 하며, 500을 곧바로 미적용으로 간주해서는 안 됩니다.

문서 평가

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