콘텐츠로 이동

멤버 추가(배포 플랜)



POST /api/v1/workspace/member/batch_add

개요

배포 플랜은 사이트에 이미 존재하는 계정을 현재 워크스페이스에 일괄 추가하고 역할을 부여합니다.

호출 전 준비 및 사용 단계

이 API는 배포 플랜에서만 지원되며, SaaS에서 호출하면 거부됩니다. 먼저 이미 존재하지만 아직 이 워크스페이스에 직접 추가되지 않은 계정과 이 워크스페이스에서 사용 가능한 역할을 준비합니다. 모든 대상 계정에는 동일한 역할 배열이 적용되며, 초대 이메일은 발송되지 않습니다. 계정 또는 역할에 유효하지 않은 값이 있으면 먼저 오류를 반환하며, 이미 직접 추가된 멤버가 포함된 경우에도 거부되므로 멱등 권한 부여 업데이트 API로 사용할 수 없습니다. 계정 또는 역할 배열이 비어 있으면 true를 바로 반환할 수 있으나, 실제 추가가 완료되었음을 의미하지는 않습니다. 모든 작업은 현재 DF-API-KEY가 속한 워크스페이스를 대상으로 합니다. 다른 워크스페이스를 사용하려면 해당 Key와 사이트 Endpoint로 변경하세요. 멤버 관계, 역할, 토큰, 캐시 등의 처리는 단계별로 저장될 수 있습니다. 예외 또는 타임아웃 발생 후에는 먼저 멤버 및 역할 상태를 조회한 뒤 재시도 여부를 결정하세요.

요청 헤더

파라미터 이름 유형 필수 설명
DF-API-KEY string Y 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예시: <DF-API-KEY>
가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다.

Body 요청 파라미터

파라미터 이름 유형 필수 설명
accountUUIDs[*] string 배열 내의 단일 문자열 식별자입니다.
예시: acnt_example
가져오기 또는 입력 방법: 배포 플랜 전용입니다. 먼저 사이트 계정 관리에서 아직 이 워크스페이스에 추가되지 않은 계정을 생성하거나 검색하여 acnt_ UUID를 확보합니다. 이 API는 사이트 계정을 생성하지 않습니다.
roleUUIDs[*] string 배열 내의 단일 문자열 식별자입니다.
예시: readOnly
가져오기 또는 입력 방법: 역할 목록의 content.data[].uuid에서 현재 워크스페이스에서 사용 가능한 역할을 가져옵니다. 내장 식별자는 wsAdmin 관리자, general 표준 멤버, readOnly 읽기 전용 멤버이며, role_로 시작하는 것은 사용자 지정 역할입니다.
accountUUIDs array Y 이 워크스페이스에 추가할 사이트의 기존 계정 UUID 배열입니다. 자동으로 중복을 제거하며 현재 호출 주체와 동일한 식별자는 건너뜁니다.
null 허용: False
예시: ["acnt_example"]
가져오기 또는 입력 방법: 배포 플랜 전용입니다. 먼저 사이트 계정 관리에서 아직 이 워크스페이스에 추가되지 않은 계정을 생성하거나 검색하여 acnt_ UUID를 확보합니다. 이 API는 사이트 계정을 생성하지 않습니다.
roleUUIDs array Y 각 신규 멤버에게 일괄 부여할 역할 UUID 배열입니다. owner를 포함할 수 없습니다. 유효한 역할을 하나 이상 지정하는 것이 좋습니다.
null 허용: False
예시: ["readOnly"]
가져오기 또는 입력 방법: 역할 목록의 content.data[].uuid에서 현재 워크스페이스에서 사용 가능한 역할을 가져옵니다. 내장 식별자는 wsAdmin 관리자, general 표준 멤버, readOnly 읽기 전용 멤버이며, role_로 시작하는 것은 사용자 지정 역할입니다.

파라미터 추가 설명

동일한 사이트 계정은 서로 다른 워크스페이스에서 다른 역할을 가질 수 있습니다. 이 API는 계정별 결과를 반환하지 않으므로, 성공 후 멤버 목록에서 확인하세요.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/workspace/member/batch_add' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"accountUUIDs":["acnt_example"],"roleUUIDs":["readOnly"]}'

응답

HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.

필드 유형 설명
content boolean 추가 처리 시 true를 반환합니다. 빈 배열이거나 추가할 유효한 대상이 없는 경우에도 true일 수 있습니다.
{
  "code": 200,
  "content": true,
  "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 객체를 제출하세요.
400 ft.OnlySupportPaasVersion SaaS 사이트에서 이 배포 플랜 API를 호출함 paas 버전만 지원 SaaS에서는 이메일 초대 또는 콘솔 권한 부여 절차를 사용하세요.
400 ft.InvalidAccountUUID 계정 UUID가 사이트에 존재하지 않거나 상태가 요구 사항을 충족하지 않음 유효하지 않은 계정 UUID: {} 사이트 계정 관리에서 유효한 계정 UUID를 다시 가져오세요.
400 ft.InvalidRoleUUID roleUUIDs에 현재 워크스페이스에서 사용할 수 없거나 삭제된 역할이 포함됨 유효하지 않은 역할 UUID: {} 역할 목록을 다시 읽고 유효한 UUID를 사용하세요.
400 ft.ForbiddenBatchAddOwner 역할 배열에 owner가 포함됨 유효하지 않은 작업입니다. 소유자를 일괄 추가할 수 없습니다. 소유자 이전에는 전용 절차를 사용하세요.
404 ft.MemberAlreadyExistsInWorkspace 대상 계정 중 하나라도 이 워크스페이스에 이미 직접 추가됨 워크스페이스에 이미 해당 멤버가 존재함 이미 존재하는 멤버를 제거하고, 역할 변경이 필요하면 멤버 수정을 사용하세요.
401 ft.WKSPNotExistOrReleased 현재 워크스페이스가 삭제되었거나 릴리스됨 워크스페이스가 존재하지 않거나 릴리스됨 Key와 워크스페이스 상태를 확인하세요.
500 ft.InternalServerError 데이터 저장, 연결된 리소스 또는 캐시 처리 실패 내부 오류 먼저 멤버와 권한의 현재 상태를 확인한 뒤 재시도 여부를 결정하세요. 계속 실패하면 traceId와 민감 정보가 제거된 요청을 제공하세요.

문서 평가

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