수정¶
POST /api/v1/workspace/{workspace_uuid}/member/batch_modify
개요¶
워크스페이스 멤버의 직접 역할을 일괄 교체합니다.
호출 전 및 사용 단계¶
w 권한의 External 자격 증명이 필요합니다. 먼저 워크스페이스 멤버 목록으로 대상 멤버의 현재 직접 역할과 상속 역할을 저장하고, 전체 대상 목록에 따라 roleUUIDs를 제출하며 onlyModifyRoles=true를 권장합니다. 현재 External 호출은 프런트엔드 멤버 편집 분기와 다르므로 memberGroupUUIDs와 acntWsNickname은 팀/닉네임에 기록되지 않습니다. 현재 Owner를 수정 대상으로 지정할 수 없습니다. 다른 단일 직접 멤버에게 owner를 부여할 수 있으며, 이 경우 다른 대상 역할은 버려지고 원래 Owner는 wsAdmin으로 강등되며 워크스페이스 멤버 관계는 유지됩니다. 여러 명을 일괄적으로 Owner로 설정하는 것은 거부됩니다. 원래 Owner의 직접 멤버 관계를 제거하려면 소유자 이전을 사용해야 합니다. 응답은 빈 객체이며 계정별 성공 목록을 반환하지 않고 대상 역할의 유효성도 보장하지 않습니다. 먼저 이 워크스페이스의 역할 목록으로 roleUUIDs의 각 항목을 검증해야 하며, 이 API가 알 수 없거나 다른 워크스페이스의 역할을 거부한다고 의존해서는 안 됩니다. 이러한 값은 연결에 기록되어 기존 직접 역할을 대체할 수 있습니다. 알 수 없거나 직접 멤버가 아닌 계정 UUID는 필터링될 수 있습니다. 기존 승인 기록은 취소될 수 있으며, 권한 및 캐시 처리는 서비스 간 원자적 작업이 아니므로 실패 후에는 현재 직접 역할을 먼저 확인한 뒤 재시도하십시오.
경로 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| workspace_uuid | string | Y | 대상 워크스페이스 UUID이며, 먼저 활성 상태와 사이트를 확인합니다. 예: wksp_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 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| accountUUIDs[*] | string | 단일 계정 UUID이며 이메일, 계정 이름 또는 워크스페이스 UUID를 입력할 수 없습니다. 예: acnt_example001가져오기 또는 입력 방법: 워크스페이스 멤버 목록의 content.data[].uuid에서 기존 멤버를 가져옵니다. 추가/이전 시에는 사이트 계정 목록에서 대상 계정을 가져올 수도 있습니다. |
|
| roleUUIDs[*] | string | 단일 유효 역할 UUID이며, 내장 역할은 실제 식별자를 사용하고 사용자 정의 역할은 반환된 uuid를 사용합니다. 예: general가져오기 또는 입력 방법: 워크스페이스 역할 목록에서 해당 워크스페이스의 유효 역할 uuid를 가져옵니다. 내장 역할은 일반적으로 general, readOnly, wsAdmin입니다. |
|
| memberGroupUUIDs[*] | string | 단일 팀 UUID이며 감사 준비에만 참여할 수 있고, 이 External 진입점을 통해 팀 변경 사항이 저장되지는 않습니다. 예: group_example001가져오기 또는 입력 방법: 현재 적용되지 않습니다. 호환 호출을 위해 제공하는 경우 팀 목록에서 실제 uuid를 가져와야 합니다. |
|
| accountUUIDs | array | Y | 필수 배열입니다. 현재 구현은 직접 관계가 있는 계정 하위 집합을 사용하며, 직접 관계가 없는 UUID가 섞이면 무시될 수 있습니다. 모두 일치하지 않으면 실패합니다. 선언상 null을 허용하지만 구현에서 set(null)은 500을 반환하므로 null을 전달하지 마십시오. 빈 배열과 onlyModifyRoles=false를 함께 사용하면 첫 번째 요소에 액세스하다 실패할 수도 있습니다. null 허용: True 예: ["acnt_example001"]가져오기 또는 입력 방법: 워크스페이스 멤버 목록에서 활성 직접 멤버 연결이 있는 계정을 선택합니다. |
| acntWsNickname | string | 선택적 문자열 또는 null이며, 사용자 지정 길이 상한은 128로 선언되어 있습니다(반각 문자는 보통 1, 기타 문자는 보통 2). 현재 External은 이 필드를 저장하지 않으므로 생략을 권장합니다. null 허용: True $maxCustomLength: 128 예: 예시 워크스페이스 닉네임가져오기 또는 입력 방법: 현재 이 External 진입점은 워크스페이스 닉네임을 기록하지 않습니다. 변경하려면 해당 기능을 지원하는 멤버 관리 진입점을 사용하십시오. |
|
| memberGroupUUIDs | array | 선택적 배열 또는 null이며 현재 멤버 팀에 적용되지 않습니다. 생략을 권장합니다. onlyModifyRoles=false일 때 감사 준비에 참여하며 null은 내부 예외를 발생시킬 수 있습니다. null 허용: True 예: []가져오기 또는 입력 방법: 현재 이 External 진입점은 팀 관계를 기록하지 않습니다. 팀 멤버를 관리해야 할 때는 해당 팀 관리 기능을 사용하십시오. |
|
| onlyModifyRoles | boolean | Y | 필수 불리언 값입니다. 현재 External은 non-front 분기를 사용하므로 false여도 팀 또는 워크스페이스 닉네임을 기록하지 않습니다. 또한 false는 단일 멤버 감사 준비를 조기에 수행하며 중복 제거 후 첫 번째 대상이 유효해야 합니다. 중복 제거에 집합을 사용하므로 순서가 보장되지 않고 첫 항목이 입력 배열의 첫 항목과 반드시 같지는 않아 실패 조건이 늘어날 수 있습니다. null 허용: False 예: true가져오기 또는 입력 방법: 이 External 진입점에서는 true로 고정하여 역할만 수정할 것을 권장합니다. |
| roleUUIDs | array | Y | 필수 전체 대상 역할 배열이며 각 대상 멤버의 직접 역할을 교체합니다. 기존 역할과 병합하지 않고 팀/백엔드 그룹 상속 역할도 제거하지 않습니다. null 또는 빈 배열일 수 없습니다. 현재 구현은 역할 존재 여부와 소속 워크스페이스를 항목별로 검증하지 않으므로 알 수 없거나 다른 워크스페이스의 UUID가 연결에 기록될 수 있지만 유효한 권한을 형성하지는 못할 수 있습니다. 먼저 이 워크스페이스의 역할 목록과 대조하여 각 항목을 검증해야 합니다. null 허용: False 예: ["readOnly"]가져오기 또는 입력 방법: 워크스페이스 역할 목록에서 해당 워크스페이스의 유효 역할 uuid를 가져옵니다. 내장 역할은 일반적으로 general, readOnly, wsAdmin입니다. |
파라미터 추가 설명¶
인증은 External API 서명 인증을 참조하십시오. 이 페이지 예제는 v20240417을 사용하며 원본 전체 경로, Query 및 요청 본문 서명 알고리즘과 함께 사용됩니다. 이 모듈은 지정된 워크스페이스의 멤버 관계 또는 역할을 조작하며 계정 자체를 생성하지 않습니다. 쓰기 요청 실패 후에는 먼저 멤버와 역할 현황을 확인한 뒤 재시도 여부를 결정해야 합니다. 역할 목록에서 유효한 UUID를 사용하고 알 수 없는 사용자 정의 역할이 완전히 거부된다고 의존하지 마십시오. 기록 후에는 실제 사용 가능한 권한을 확인해야 합니다.
요청 예시¶
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/workspace/wksp_example001/member/batch_modify'
query = {}
data = {'accountUUIDs': ['acnt_example001'], 'roleUUIDs': ['readOnly'], 'onlyModifyRoles': 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, application/json 공통 래퍼이며 비즈니스 데이터는 content에 있습니다. External은 declaration에 자동으로 추가되지 않으며, 목록 페이지네이션은 content.pageInfo를 유지합니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | object | 이 External 분기는 성공 시 {}를 반환하며, 프런트엔드 승인 분기의 autoLoginUrl, needOwnerAudit 또는 계정별 결과를 반환하지 않습니다. |
{
"code": 200,
"content": {},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 쓰로틀링 및 공통 요청 오류는 공용 오류 정의를 참조하십시오.
아래 표는 확인된 비즈니스 및 요청 오류입니다. 일반 데이터베이스/다운스트림 5xx 또는 처리되지 않은 예외는 전역에서 ft.InternalServerError로 래핑됩니다. 쓰기 요청 실패 시 부분 적용이 없음을 보장하지 않으므로 먼저 관계 현황을 확인해야 합니다.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인하십시오. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하십시오. |
| 400 | ft.JsonFormatError | 요청 JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | JSON 객체를 제출하고 배열이나 null을 전체 요청 본문으로 사용하지 마십시오. |
| 400 | ft.SSOUnsupportModifyRole | 대상 SSO 계정의 네임스페이스에 이 워크스페이스에서 활성화된 SAML 역할 매핑이 존재함 | SAML 매핑이 활성화되어 SSO 계정의 역할을 수정할 수 없습니다. | 해당 ID 공급자의 역할 매핑을 통해 조정하거나 관리자가 매핑 정책을 확인하도록 하십시오. |
| 400 | ft.RoleUUIDNullError | roleUUIDs가 빈 배열임 | 역할 uuid 목록이 비어 있음 | 하나 이상의 대상 역할을 제공하십시오. |
| 400 | ft.ForbiddenBatchModifyOwner | 중복 제거된 여러 대상 계정에 동시에 owner 역할을 요청함 | 유효하지 않은 작업입니다. 소유자를 일괄 수정할 수 없습니다. | Owner는 한 번에 하나의 대상으로만 변경할 수 있습니다. 명확한 이전 절차를 사용하십시오. |
| 400 | ft.ForbiddenModifyOwner | 수정 대상에 현재 Owner 계정이 포함됨 | 유효하지 않은 작업입니다. 소유자를 수정할 수 없습니다. | 현재 Owner를 배치에서 제거하고, 이전이 필요하면 전용 API를 사용하십시오. |
| 400 | ft.MemberRoleNotFound | 대상에 활성 직접 멤버 연결이 없음 | 현재 워크스페이스에서 지정된 멤버 역할을 찾을 수 없습니다. | 먼저 추가 API를 통해 직접 관계를 설정하십시오. 백엔드 그룹 상속 멤버는 직접 멤버와 같지 않습니다. |
| 400 | ft.AgentMemberCanNotBeOwner | Owner를 부여하려는 유효 대상이 agent 출처 멤버임 | agent 출처 멤버는 워크스페이스 소유자로 설정할 수 없습니다. | 일반 멤버 계정을 Owner로 선택하십시오. |
| 404 | ft.NotFoundAccount | onlyModifyRoles=false일 때 감사 준비에 사용되는 중복 제거 후 첫 번째 계정에 활성 직접 멤버 관계가 없음. 집합 중복 제거 순서는 보장되지 않음 | 지정된 계정을 찾을 수 없습니다. | onlyModifyRoles=true를 사용하고 유효한 직접 멤버를 선택하십시오. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시, 기존 승인 작업 취소 또는 처리되지 않은 배열/필드 예외. accountUUIDs=null이거나 onlyModifyRoles=false이고 대상 배열이 비어 있음/감사 입력 예외 | 내부 오류 | traceId를 저장하고 관리자가 실제 관계와 캐시를 확인하도록 하십시오. 쓰기 작업이 이미 일부 커밋되었을 수 있으므로 무작정 재실행해서는 안 됩니다. |