수정¶
POST /api/v1/account/{account_uuid}/modify
개요¶
지정한 계정의 기본 프로필, 비즈니스 속성 및 세션 시간을 수정합니다.
호출 전 준비 및 사용 단계¶
External 자격 증명에 대한 w 권한이 필요합니다. 경로의 account_uuid는 계정 목록 또는 생성 응답에서 가져옵니다. 업데이트할 필드만 제출하며, 생략하면 기존 값이 유지됩니다. attributes와 customAttributes는 객체 전체를 교체합니다. 정상 또는 비활성화된 계정을 수정할 수 있습니다. 이 API를 통해 계정의 exterId, 브랜드, 언어, 비활성화 상태 또는 워크스페이스 역할을 변경할 수는 없습니다. 수정하면 계정 프로필 캐시가 지워지고, 변경 사항에 따라 관련 알림 설정이 비동기적으로 새로 고쳐집니다. 성공이 기존 로그인 Token이 모두 취소되었음을 의미하지는 않습니다.
경로 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| account_uuid | string | Y | 대상 계정 UUID. 예: acnt_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 초 문자열을 생성합니다. |
Body 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| attributes | json | 선택 사항이며, 생략하면 유지됩니다. 제공하면 객체 전체를 교체하고, {}는 비우는 것이며 병합 패치가 아닙니다. 이후 SSO 로그인으로 덮어쓸 수 있으며, null일 수 없습니다. null 허용: False 예: {"部门": "研发部"}가져오기 또는 입력 방법: SSO 계정 속성 매핑에 따라 조직 대상의 전체 객체를 구성합니다. |
|
| countryCode | string | 선택 사항입니다. 이 필드만 전송하면 기존 휴대폰 번호와 결합하여 검증 및 정규화합니다. 번호를 변경할 때는 두 필드를 함께 전송하는 것이 좋습니다. mobile이 비어 있으면 최종적으로 국가/지역 코드도 비워지며, null은 유효하지 않습니다. 빈 문자열 허용: True null 허용: False 예: 1가져오기 또는 입력 방법: mobile과 함께 대상 국가/지역 코드를 제출합니다. |
|
| customAttributes | json | 선택 사항이며, 생략하면 유지됩니다. 제공하면 객체 전체를 교체하고, {}는 비우는 것이며 병합 패치가 아니고 null일 수 없습니다. null 허용: False 예: {"costCenter": "CC-1001"}가져오기 또는 입력 방법: 비즈니스 측에서 저장해야 하는 전체 속성 KV 객체를 사용합니다. |
|
| string | 선택 사항이며, 생략하면 기존 값이 유지됩니다. 빈 문자열은 값을 비우고, null은 유효하지 않습니다. 현재 수정 시에는 이메일 형식 검증이 없으므로 호출자가 직접 검증해야 하며, 최대 256자입니다. 빈 문자열 허용: True null 허용: False 최대 길이: 256 예: xxx@guance.com가져오기 또는 입력 방법: 알림을 수신할 수 있는 유효한 이메일을 사용합니다. |
||
| mobile | string | 휴대폰 필드는 countryCode와 로컬 mobile 두 부분으로 구성됩니다. + 국제 번호 또는 00 접두사 국제 번호를 지원하며, 1로 시작하는 11자리 기존 국내 번호는 기본적으로 86을 사용할 수 있습니다. 국가/지역 코드를 제공하면 전체 번호의 유효성을 검증합니다. 선택 사항이며, 생략하면 기존 번호가 유지됩니다. 명시적 빈 문자열은 번호와 국가/지역 코드를 동시에 비우며, null은 유효하지 않습니다. 빈 문자열 허용: True null 허용: False 예: 2025550123가져오기 또는 입력 방법: 멤버 프로필에서 가져오며, countryCode와 함께 제출하면 기존 국가/지역 코드가 사용되는 것을 피할 수 있습니다. |
|
| name | string | 선택 사항이며, 생략하면 기존 값이 유지됩니다. 비어 있지 않은 문자열을 제공하고 null을 전송하지 마세요. null 허용: False 예: 示例成员新名称가져오기 또는 입력 방법: 멤버의 최신 표시 닉네임을 사용합니다. |
|
| password | string | 선택 사항이며, 생략하면 기존 비밀번호가 유지됩니다. 비어 있지 않은 비밀번호는 최소 8자이며 네 가지 문자 유형 중 최소 세 가지를 포함해야 합니다. 현재 빈 문자열은 기존 비밀번호를 유지하는 대신 빈 비밀번호 해시로 재설정되므로 클라이언트는 빈 문자열을 금지해야 하며, null은 유효하지 않습니다. null 허용: False 예: Changed!2026a가져오기 또는 입력 방법: 호출자가 새로운 안전한 비밀번호를 제공합니다. |
|
| source | string | 선택 가능한 열거형 값은 local, unknown, oidc, ldap이며, 생략하면 유지됩니다. 현재는 값만 할당하고 exterId를 자동으로 변경하거나 source와 exterId의 관계를 검사하지 않습니다. 빈 문자열은 기록할 수 있지만, null은 선언상 통과하더라도 데이터베이스 500 오류를 유발할 수 있으므로 유효한 열거형 값만 사용하는 것이 좋습니다. 빈 문자열 허용: True null 허용: True 선택 가능한 값: ['local', 'unknown', 'oidc', 'ldap'] 예: oidc가져오기 또는 입력 방법: 실제 연동된 ID 공급자와 일치해야 합니다. 로컬 계정은 local을 사용하고, 타사 계정은 ID 시스템에 따라 unknown, oidc 또는 ldap을 선택합니다. |
|
| tokenHoldTime | integer | 선택 사항이며, 생략하면 유지됩니다. 계정의 무작업 세션 유지 시간으로, 단위는 초이며 범위는 1800~604800이고 null일 수 없습니다. 빈 문자열 허용: False null 허용: False $maxValue: 604800 $minValue: 1800 예: 86400가져오기 또는 입력 방법: 조직의 계정 보안 정책에 따라 초 단위 값을 선택합니다(1800~604800). |
|
| tokenMaxValidDuration | integer | 선택 사항이며, 생략하면 유지됩니다. 계정 세션의 최대 유효 기간으로, 단위는 초이며 범위는 60~2592000이고 null일 수 없습니다. 빈 문자열 허용: False null 허용: False $maxValue: 2592000 $minValue: 60 예: 604800가져오기 또는 입력 방법: 조직 보안 정책에 따라 초 단위 값을 선택합니다(60~2592000). |
|
| username | string | 선택 사항이며, 생략하면 기존 값이 유지됩니다. 해당 네임스페이스 내에서 삭제되지 않은 다른 계정과 중복되어서는 안 됩니다. username을 수정해도 email이 자동으로 동기화되지 않으므로 필요에 따라 email도 함께 제공해야 합니다. null을 전송하지 마세요. null 허용: False 예: xxx@guance.com가져오기 또는 입력 방법: 새 로그인 계정 이름을 사용합니다. 수정 전에 동일한 ID 네임스페이스 내에서 사용 중이 아닌지 확인합니다. |
파라미터 추가 설명¶
사이트 수준 External API 자격 증명을 사용하며, 인증 방식은 External API 서명 인증을 참고하세요. 아래 예시는 v20240417 서명 버전을 사용하며, 서명 경로, Query 인코딩 및 원본 요청 본문은 실제 전송 내용과 완전히 일치해야 합니다. 반환되는 계정 프로필에는 password 필드가 포함되지 않으며, mfaSecret은 고정 마스크일 뿐 로그인에 사용할 수 있는 키가 아닙니다. source를 수정해도 ID 공급자 설정이 전환되지 않으므로 타사 계정을 local로 직접 표시하는 것을 피해야 합니다. 세션 시간의 새 값은 인증 경로에 따라 적용되며, 강제 로그아웃의 대체 수단으로 사용해서는 안 됩니다.
표의 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/acnt_example001/modify'
query = {}
data = {'name': '示例成员新名称', 'email': 'xxx@guance.com', '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 | 사이트 내 계정 레코드 일련번호로, 프로필 반환에만 사용됩니다. 다른 API를 호출할 때는 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 시스템의 고유 ID이며, 로컬 계정은 일반적으로 비어 있습니다. |
| content.extend | object 또는 null | 기존 확장 프로필이며, user_icon 아바타 주소를 포함할 수 있습니다. 이 API 생성 시 전달한 extend는 현재 저장되지 않으며, 수정 API에서도 이 입력 파라미터를 공개하지 않습니다. |
| content.extend.user_icon | string | 선택적 아바타 URL 또는 정적 리소스 파일명입니다. 기존 프로필을 읽을 때 나타날 수 있으며, 이 페이지에서 쓸 수 있는 파라미터는 아닙니다. |
| content.source | string | ID 소스 식별자입니다. 예: local, unknown, oidc, ldap. agent 등 과거 내부 소스도 존재할 수 있습니다. |
| content.nameSpace | string | ID 네임스페이스이며, 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 | 계정 추가 상태 식별자이며, 설정되지 않으면 비어 있습니다. |
| content.userIconUrl | string 또는 null | 기존 아바타 설정에 따라 생성된 URL이며, 아바타가 없으면 null입니다. |
{
"code": 200,
"content": {
"id": 1001,
"uuid": "acnt_example001",
"status": 0,
"creator": "SYS",
"updator": "external",
"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": "",
"userIconUrl": null
},
"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을 최상위로 전송하지 마세요. |
| 404 | ft.NotFoundAccount | 조회 조건을 만족하는 계정을 찾을 수 없거나 계정이 이미 삭제됨 | 지정된 계정을 찾을 수 없음 | 계정 목록에서 유효한 uuid를 다시 가져옵니다. 두 조건으로 조회하는 경우 두 값이 동일한 계정에 속하는지 확인합니다. |
| 400 | ft.InvalidPasswordRule | 로컬 생성 비밀번호가 null, 빈 문자열이거나 강도 규칙을 충족하지 않음; 수정 시 제공한 비어 있지 않은 비밀번호가 강도 규칙을 충족하지 않음 | 유효하지 않은 비밀번호 규칙 | 비밀번호는 최소 8자이며, 숫자, 대문자, 소문자, 특수 문자 네 가지 유형 중 최소 세 가지를 포함해야 합니다. |
| 400 | ft.UsernameExterIdExists | username이 동일 네임스페이스 내 다른 미삭제 계정에 의해 사용 중임 | username/exterId가 이미 존재함 | 사용하지 않은 로그인 이름을 선택합니다. 먼저 목록을 조회하여 기존 계정을 확인합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시, 비동기 작업 전달 또는 명시적으로 처리되지 않은 필드 이상 | 내부 오류 | traceId를 저장하고 관리자에게 문의합니다. 쓰기 요청은 먼저 계정의 현재 상태를 다시 조회하여 확인한 후 재시도 여부를 결정하며, 500을 곧바로 미적용으로 간주해서는 안 됩니다. |