콘텐츠로 이동

멤버 수정



POST /api/v1/workspace/member/batch_modify

개요

현재 워크스페이스 멤버의 전체 직접 역할 집합을 수정하며, 단일 멤버의 팀과 닉네임을 동시에 조정할 수 있습니다.

호출 전 및 사용 단계

onlyModifyRoles=true는 일괄 역할 교체에 적합합니다. false는 단일 멤버에 사용하며, 이때 accountUUID를 하나만 전달하고 팀 배열과 닉네임은 모두 대상 전체 값으로 제출합니다. 생략하면 기존 팀 또는 닉네임이 지워집니다. 역할은 전체 교체되며, 역할 배열을 추가 목록으로 취급해서는 안 됩니다. owner는 대상 계정이 될 수 없으며, 이 API를 통해 owner를 부여할 수도 없습니다. SAML 매핑이 활성화된 관련 SSO 계정은 수동 역할 변경이 거부될 수 있습니다. 현재 코드에서는 청구 센터의 권한 상향 승인이 제거되었으며, "승인 불필요 역할"을 섞어 넣을 필요가 없습니다. 성공 시 일반적으로 content={}를 반환하며, 새로운 승인 리디렉션 필드도 제공하지 않습니다. 전달된 일부 계정이 직접적인 워크스페이스 관계를 가지고 있지 않더라도 개별 오류 보고를 보장하지 않습니다. 현재 API는 roleUUIDs가 모두 이 워크스페이스에 속하는지 완전히 검증하지 않으므로, 알 수 없거나 다른 워크스페이스의 UUID를 기록하여 기존 역할을 교체할 수 있습니다. 클라이언트는 먼저 이 워크스페이스의 역할 목록으로 각 항목을 검증해야 하며, 성공 시 반환된 빈 객체는 새 역할의 유효성을 증명하지 않습니다. 실행 후에는 실제 역할과 액세스 권한을 조회해야 합니다. 멤버 관계, 역할, 토큰, 캐시 등의 처리는 단계별로 저장될 수 있습니다. 예외 또는 타임아웃 발생 후에는 먼저 멤버 및 역할 상태를 읽은 다음 재시도를 결정하십시오.

요청 헤더

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

Body 요청 파라미터

파라미터명 타입 필수 설명
accountUUIDs[*] string 배열 내 단일 문자열 식별자입니다.
예: acnt_example
획득 또는 입력 방법: 워크스페이스 멤버 목록의 content.data[].uuid에서 현재 워크스페이스 멤버 계정 UUID를 획득합니다. API Key UUID 또는 이메일이 아닙니다.
roleUUIDs[*] string 배열 내 단일 문자열 식별자입니다.
예: readOnly
획득 또는 입력 방법: 역할 목록의 content.data[].uuid에서 현재 워크스페이스에서 사용 가능한 역할을 획득합니다. 내장 식별자: wsAdmin 관리자, general 표준 멤버, readOnly 읽기 전용 멤버이며, role_로 시작하는 역할은 사용자 정의 역할입니다.
memberGroupUUIDs[*] string 단일 팀 UUID이며 group_로 시작합니다.
예: group_example
획득 또는 입력 방법: 이 워크스페이스의 팀 관리 또는 워크스페이스 멤버 목록의 member_group[].uuid에서 획득합니다.
accountUUIDs array Y 기존 멤버 계정 배열입니다. onlyModifyRoles=false인 경우 클라이언트는 계정을 하나만 제출해야 하며, 첫 번째 계정의 팀/닉네임 업데이트가 불확실해지는 것을 방지합니다. null을 전달하지 마십시오.
null 허용: True
예: ["acnt_example"]
획득 또는 입력 방법: 워크스페이스 멤버 목록의 content.data[].uuid에서 현재 워크스페이스 멤버 계정 UUID를 획득합니다. API Key UUID 또는 이메일이 아닙니다.
acntWsNickname string onlyModifyRoles=false일 때 업데이트합니다. 생략하면 기본값이 빈 문자열이며 기존 닉네임을 지울 수 있고, true일 때는 무시합니다. 최대 128 사용자 정의 길이 단위이며, ASCII/반각 가타카나는 1, 한자 등은 일반적으로 2로 계산합니다.
null 허용: True
$maxCustomLength: 128
예: 生产值班工程师
획득 또는 입력 방법: 비즈니스 담당자가 해당 멤버를 위해 이 워크스페이스의 닉네임을 입력합니다. 전체 사이트 계정 name이 아닙니다.
memberGroupUUIDs array onlyModifyRoles=false일 때의 전체 대상 팀 목록입니다. 생략하거나 []를 전달하면 기존 팀이 제거되므로 null을 전달하지 마십시오. true일 때는 팀을 수정하지 않습니다.
null 허용: True
예: ["group_example"]
획득 또는 입력 방법: 현재 워크스페이스의 팀 관리 또는 워크스페이스 멤버 목록의 member_group[].uuid에서 획득합니다. false 모드를 사용할 때 전체 대상 배열을 제출하십시오.
onlyModifyRoles boolean Y 필수 boolean입니다. true이면 팀과 닉네임을 유지하고, false이면 하나의 accountUUID만 제출하고 대상 팀과 닉네임을 함께 제공해야 합니다.
null 허용: False
예: true
획득 또는 입력 방법: 여러 멤버의 역할을 일괄 변경하려면 true를 사용하고, 한 멤버의 팀/닉네임을 함께 변경하려면 false를 사용합니다.
roleUUIDs array Y 전체 대상 직접 역할 집합이며 비어 있으면 안 됩니다. 기존 직접 역할을 교체하며, 그룹/팀 상속 역할은 해당 관계에 따라 별도로 적용됩니다. owner를 포함해서는 안 됩니다.
null 허용: False
예: ["readOnly"]
획득 또는 입력 방법: 역할 목록의 content.data[].uuid에서 현재 워크스페이스에서 사용 가능한 역할을 획득합니다. 내장 식별자: wsAdmin 관리자, general 표준 멤버, readOnly 읽기 전용 멤버이며, role_로 시작하는 역할은 사용자 정의 역할입니다.

추가 파라미터 설명

이 공개 API에는 remark 등의 내부 파라미터가 없습니다. accountUUIDs에는 null 허용이라는 과거 선언이 있지만 현재 구현에서는 배열이 필요합니다. false 모드에서 빈 배열을 전달하면 내부 오류가 발생할 수 있습니다. 클라이언트는 예시에 따라 비어 있지 않은 배열을 전달하고, 역할 목록에서 사용 가능한 UUID를 획득하십시오.

요청 예시

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

응답

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

필드 타입 설명
content object 현재 정상 흐름에서는 빈 객체 {}를 반환하며, declaration을 추가하지 않고 계정별 업데이트 결과를 제공하지 않습니다.
{
  "code": 200,
  "content": {},
  "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.SSOUnsupportModifyRole 대상 SSO 계정의 역할이 SAML 매핑이 활성화된 ID 공급자에 의해 관리됨 SAML 매핑 활성화, SSO 계정 역할 수정 금지 해당 ID 공급자 또는 매핑 규칙에서 조정하여 로컬 덮어쓰기를 피하십시오.
400 ft.RoleUUIDNullError roleUUIDs가 비어 있음 역할 uuid 목록이 비어 있음 이 워크스페이스에서 유효한 역할을 하나 이상 제공하십시오.
400 ft.InvalidActionSaasLimit 대상 역할 집합에 owner 포함 유효하지 않은 작업, SaaS에서는 소유자를 수정할 수 없습니다. 소유자 이전 절차를 사용하십시오.
400 ft.ForbiddenModifyOwner 대상 계정이 현재 워크스페이스 소유자임 유효하지 않은 작업, 소유자를 수정할 수 없습니다. owner 계정을 수정하지 말고 소유자 이전 절차를 사용하십시오.
404 ft.WorkspaceNoExistsOwner 현재 워크스페이스에서 유효한 소유자 관계를 찾을 수 없음 워크스페이스에 소유자가 없습니다. 먼저 관리자에게 문의하여 워크스페이스 소유자 상태를 확인하십시오.
400 ft.MemberRoleNotFound 조작할 수 있는 현재 워크스페이스의 직접 멤버 관계가 없음 현재 워크스페이스에서 지정된 멤버 역할을 찾을 수 없습니다. 현재 멤버 목록에서 계정 및 직접 멤버 자격을 확인하십시오.
500 ft.InternalServerError 데이터 저장, 관련 리소스 또는 캐시 처리 실패 내부 오류 먼저 멤버 및 권한의 현재 상태를 확인한 후 재시도를 결정하십시오. 계속 실패하면 traceId와 민감 정보를 제거한 요청을 제공하십시오.
404 ft.NotFoundAccount onlyModifyRoles=false일 때 단일 사용자 감사에 사용할 계정에 활성 직접 멤버 관계가 없음 지정된 계정을 찾을 수 없음 이 모드에서는 유효한 직접 멤버 UUID 하나만 제출하십시오. 여러 계정을 중복 제거한 후의 첫 항목이 입력 순서를 유지한다고 보장할 수 없습니다.

문서 평가

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