콘텐츠로 이동

멤버 추가



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를 저장하고 관리자에게 실제 관계와 캐시를 확인하도록 요청하십시오. 쓰기 작업이 일부 커밋되었을 수 있으므로 무작정 재시도해서는 안 됩니다.

문서 평가

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