수정¶
POST /api/v1/mgroup/{group_uuid}/modify
개요¶
백엔드 그룹 이름을 수정하고 전체 계정 목록에 따라 멤버를 재설정합니다.
호출 전 및 사용 단계¶
먼저 백엔드 그룹 목록을 호출하고 showMembers를 활성화하여 기존 전체 멤버를 저장한 후, 대상 목록을 제출합니다. 이는 전체 교체이며 증분 추가가 아닙니다. accountUUIDs가 지정된 후 나열되지 않은 기존 멤버 관계는 제거됩니다. accountUUIDs를 생략하면 멤버가 유지되고, null 또는 []는 멤버를 비웁니다. 이름만 수정할 때는 빈 배열을 포함하지 마세요. name을 생략하면 이름이 유지되며, 둘 다 생략하면 관계를 변경하지 않고 true를 반환할 수 있습니다. 백엔드 그룹에서 멤버를 제거하면 해당 그룹을 통해 상속되는 공간 액세스/역할이 변경되며, 계정 자체나 기타 직접 멤버 관계는 삭제되지 않습니다. 그룹/관계 상태가 먼저 커밋된 후 권한 캐시 새로 고침이 전달됩니다. HTTP200은 이후 모든 요청이 즉시 새 권한을 사용함을 보장하지 않으며, 전달 또는 감사 실패로 인한 500도 본문 저장 이후에 발생할 수 있습니다. 먼저 목록을 페이지 단위로 읽고 uuid로 위치를 찾으며, 수정 시 전체 members/refWorkspaces를 펼쳐 확인하고, 삭제 시 대상이 더 이상 활성 목록에 없는지 확인한 후 재시도를 결정합니다. 새로 고침 대상 목록이 비어 있으면 공유 작업이 모든 활성 공간을 새로 고치며, 현재 그룹만 새로 고친다고 이해해서는 안 됩니다.
라우트 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| group_uuid | string | Y | 활성 백엔드 그룹 UUID이며 단일 공간의 group_ 팀 UUID가 아닙니다. 예시: mgroup_example001획득 또는 입력 방법: 백엔드 그룹 목록의 content.data[].uuid에서 가져옵니다. |
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 원본 경로와 요청 본문 서명 버전이며, 생략하고 이 페이지의 알고리즘을 계속 사용할 수는 없습니다. 예시: v20240417획득 또는 입력 방법: 이 페이지의 예시는 이 고정 버전을 사용하며 예시 서명 알고리즘과 함께 사용됩니다. |
|
| X-Df-Access-Key | string | Y | 읽기 인터페이스는 r 또는 w 자격 증명을 사용할 수 있고, 쓰기 인터페이스는 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에서 단일 계정을 가져옵니다. |
|
| accountUUIDs | array | 계정 UUID 전체 배열이며 집합 기준으로 중복을 제거합니다. 호출자는 계정 존재 여부와 필요한 상태를 사전에 검증해야 하며, 인터페이스는 알 수 없거나 이미 삭제된 계정을 자동으로 필터링하지 않습니다. 생략하면 유지되고, 명시적 null 또는 []는 모든 멤버를 비우며, 비어 있지 않은 배열은 전체를 교체합니다. null 허용: True 예시: ["acnt_example001"]획득 또는 입력 방법: 사이트 계정 목록의 content.data[].uuid에서 실제 계정을 가져오고, 먼저 상태를 확인합니다. |
|
| name | string | 선택 사항이며 최대 256자입니다. null일 수 없으며, 비어 있지 않은 이름을 제공할 것을 권장합니다. null 허용: False 최대 길이: 256 예시: 示例研发分组新名称획득 또는 입력 방법: 필요에 따라 새 이름을 입력하며, 유지하려면 생략합니다. |
파라미터 추가 설명¶
사이트 수준 External API AK/SK를 사용하며, 서명 방식은 External API 서명 인증을 참조하세요. 백엔드 그룹 mgroup_는 여러 공간에 연결되어 상속 역할을 부여할 수 있으며, 단일 워크스페이스 내의 group_ 팀과 동일한 종류의 객체가 아닙니다. 쓰기 요청에는 w 권한이 필요하고, 목록은 r 또는 w를 사용할 수 있습니다. 멤버 변경 후 관련 공간 멤버 권한 캐시를 비동기로 새로 고칩니다. HTTP200이 모든 세션이 새 권한을 소비했음을 의미하지는 않습니다. 그룹 엔터티의 updateAt은 순수 멤버 변경을 반영한다고 보장할 수 없습니다.
요청 예시¶
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/mgroup/mgroup_example001/modify'
query = {}
data = {'name': '示例研发分组新名称', 'accountUUIDs': ['acnt_example001']}
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"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
표에는 확인된 요청 및 비즈니스 오류를 나열합니다. 일반적인 내부 예외는 최종적으로 500 ft.InternalServerError가 됩니다. 그룹/관계는 이미 커밋되었을 수 있고 이후 캐시 또는 감사가 실패했을 수 있으므로, 먼저 현재 상태를 읽어야 하며 오류만으로 적용되지 않았다고 추론해서는 안 됩니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방식 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 표에 따라 JSON 객체를 제출합니다. |
| 404 | ft.MGroupNoExists | 그룹 UUID가 존재하지 않거나 그룹이 삭제됨 | 그룹이 존재하지 않음 | 백엔드 그룹 목록에서 활성 mgroup_ 레코드 uuid를 가져옵니다. |
| 400 | ft.MGroupNameExists | 동일한 이름의 활성 백엔드 그룹이 이미 존재 | 동일한 이름의 그룹이 이미 존재 | 먼저 목록을 조회하여 중복되지 않는 이름을 선택합니다. 기존 그룹은 수정해야 하며 중복 생성하지 마세요. |
| 500 | ft.InternalServerError | 데이터베이스, 비동기 캐시 새로 고침 전달, 감사 또는 처리되지 않은 필드 예외 | 내부 오류 | traceId를 저장하고 목록에서 그룹/멤버/역할 현재 상태를 확인합니다. 데이터가 이미 커밋되었을 수 있으므로 무작정 중복 생성하거나 전체 덮어쓰지 마세요. |