멤버 추가¶
POST /api/v1/workspace/{workspace_uuid}/member/batch_add
개요¶
사이트에 이미 존재하는 계정을 워크스페이스에 일괄 추가하고 동일한 역할을 부여합니다.
호출 전 및 사용 단계¶
w 권한이 있는 External 자격 증명이 필요합니다. 먼저 사이트 계정 목록에서 기존 계정을 선택한 다음 워크스페이스 역할 목록에서 이 워크스페이스에서 사용 가능한 역할을 선택합니다. 이 API는 계정을 생성하지 않으며 계정 생성 이메일도 발송하지 않습니다. 계정은 정상 또는 비활성 상태일 수 있지만, 비활성 계정은 정상적으로 로그인할 수 없으며 이 모듈의 멤버 목록에 나타나지 않습니다. 계정 UUID를 중복 제거한 후 항목별로 검증하며, 유효하지 않은 계정이나 역할이 하나라도 있으면 먼저 오류를 반환합니다. 워크스페이스에 정상적으로 이미 추가된 직접 멤버를 다시 추가하면 중복 오류가 발생하며, 이를 멱등 성공으로 간주할 수 없습니다. 빈 계정 배열 또는 빈 역할 배열은 기존 검증을 완료한 후 관계를 새로 추가하지 않고 true를 바로 반환할 수 있으므로, 클라이언트는 의도하지 않은 빈 작업을 금지해야 합니다. 일괄 추가로 owner를 부여할 수 없으며, 소유자는 이전 API를 사용하십시오.
경로 매개변수¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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입니다. |
|
| accountUUIDs | array | Y | 필수 문자열 배열이며, 중복 제거 후 status=0 또는 2인 기존 계정만 허용합니다. null은 유효하지 않고 []는 새로 추가하지 않습니다. null 허용: False 예시: ["acnt_example001"]획득 또는 입력 방법: 워크스페이스 멤버 목록의 content.data[].uuid에서 기존 멤버를 가져옵니다. 추가/이전 시에는 사이트 계정 목록에서 대상 계정을 가져올 수도 있습니다. |
| roleUUIDs | array | Y | 필수 문자열 배열이며 역할은 현재 워크스페이스의 유효 범위에 있어야 합니다. 여러 개를 지정할 수 있지만 owner를 포함할 수 없습니다. null은 유효하지 않고 []는 새로 추가하지 않습니다. null 허용: False 예시: ["general"]획득 또는 입력 방법: 워크스페이스 역할 목록에서 해당 워크스페이스의 유효한 역할 uuid를 가져오며, 일반적으로 기본 제공되는 역할은 general, readOnly, wsAdmin입니다. |
매개변수 추가 설명¶
인증은 External API 서명 인증을 참조하십시오. 이 페이지의 예시는 v20240417을 사용하며 원본 전체 경로, Query 및 요청 본문 서명 알고리즘과 함께 사용됩니다. 이 모듈은 지정된 워크스페이스의 멤버 관계 또는 역할을 조작하며 계정 자체를 생성하지 않습니다. 쓰기 요청이 실패하면 먼저 멤버와 역할의 현재 상태를 확인한 후 재시도 여부를 결정해야 합니다. 이 작업은 직접 멤버와 역할 연결을 새로 추가하고 기존 초대 기록을 업데이트합니다. 성공 시 계정별 상태를 반환하지 않으므로 실패 후에는 항목별로 확인하십시오.
요청 예시¶
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_add'
query = {}
data = {'accountUUIDs': ['acnt_example001'], 'roleUUIDs': ['general']}
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이며 새로 추가된 건수가 아닙니다. 빈 작업도 true일 수 있습니다. |
{
"code": 200,
"content": true,
"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.InvalidAccountUUID | 중복 제거 후 계정 목록에 존재하지 않거나 삭제되었거나 status가 0/2가 아닌 계정이 포함됨 | 유효하지 않은 계정 UUID: {} | 사이트 계정 목록에서 유효한 uuid를 다시 선택합니다. |
| 400 | ft.InvalidRoleUUID | roleUUIDs에 현재 워크스페이스의 유효 범위에 없는 역할이 포함됨 | 유효하지 않은 역할 UUID: {} | 해당 워크스페이스 역할 목록에서 반환된 유효한 uuid를 사용합니다. |
| 400 | ft.ForbiddenBatchAddOwner | 실제 추가 요청의 roleUUIDs에 owner가 포함됨 | 유효하지 않은 작업: 소유자를 일괄 추가할 수 없습니다. | 일반 역할로 멤버를 추가하고, Owner 변경이 필요하면 이전 API를 사용합니다. |
| 404 | ft.MemberAlreadyExistsInWorkspace | 계정 status=0이며 이미 이 워크스페이스의 활성 직접 멤버 연결이 존재함 | 워크스페이스에 이미 이러한 멤버가 존재합니다. | 먼저 기존 멤버를 확인하고, 역할 업데이트는 일괄 수정을 사용하며 중복 추가하지 않습니다. |
| 401 | ft.WKSPNotExistOrReleased | 실제로 추가할 관계가 있을 때 워크스페이스가 존재하지 않거나 활성 상태가 아님 | 워크스페이스가 존재하지 않거나 이미 해제되었습니다. | 워크스페이스 목록에서 활성 워크스페이스를 선택합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시, 이전 승인 작업 취소 또는 처리되지 않은 배열/필드 예외 | 내부 오류 | traceId를 저장하고 관리자에게 실제 관계와 캐시를 확인하도록 요청하십시오. 쓰기 작업이 일부 커밋되었을 수 있으므로 무작정 재시도해서는 안 됩니다. |