콘텐츠로 이동

수정



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를 저장하고 목록에서 그룹/멤버/역할 현재 상태를 확인합니다. 데이터가 이미 커밋되었을 수 있으므로 무작정 중복 생성하거나 전체 덮어쓰지 마세요.

문서 평가

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