수정¶
POST /api/v1/workspace/declaration/modify
개요¶
현재 워크스페이스 선언을 전체 교체하며, 사용자 정의 필드는 문자열로 변환되고 조직 식별자는 시스템에서 관리합니다.
호출 전 및 사용 단계¶
대상 워크스페이스의 API Key를 사용합니다. 워크스페이스는 Key로 결정되며, Query 또는 Body에 workspaceUUID를 별도로 전달할 수 없습니다. 워크스페이스 선언은 비즈니스 식별 및 응답 표시에 사용되는 키-값 구성이며, 데이터 액세스 권한 부여, 청구 조직 마이그레이션 또는 리소스 이름 변경 인터페이스가 아닙니다.
먼저 전체 선언을 읽고 백업한 다음 declaration 객체를 제출합니다. 수정은 기존 구성을 전체 교체합니다. 제출하지 않은 사용자 정의 키는 제거되며, {}는 기존 사용자 정의 키를 비웁니다. organization은 서버에서 강제로 덮어씁니다. business는 생략/null이면 빈 문자열이 되고, 문자열은 앞뒤 공백을 제거하며, 그 외 값은 JSON 문자열로 변환됩니다. 나머지 문자열이 아닌 사용자 정의 값도 JSON 문자열로 변환됩니다. 속성 값으로 소속 조직이나 권한을 변경하는 것은 지원하지 않습니다.
free/freeEdition 워크스페이스는 현재 저장하지 않고 바로 true를 반환하므로, HTTP 200을 실제 변경으로 간주해서는 안 됩니다. 나머지 버전은 제출 후 캐시를 새로 고칩니다. 유료 플랜에서 조직 정보를 사용할 수 없으면 쓰기가 실패할 수 있으며, 배포 플랜의 organization은 고정된 default_private_organization입니다. 성공 시 불리언 값만 반환되므로 다시 읽어 확인하십시오. 캐시 새로 고침 실패는 제출 이후에 발생할 수 있으므로, 오류 발생 후 먼저 다시 읽고 재시도 여부를 결정하십시오. 백그라운드 조직 동기화에서도 선언 값을 다시 조정할 수 있으므로, 조직 관련 필드는 서버 결과를 기준으로 합니다.
요청 헤더¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Body 요청 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| declaration.organization | string | 전달하더라도 시스템 값으로 덮어쓰며, 조직 전환에 사용할 수 없습니다. 예: organization_example획득 또는 입력 방법: 서버가 워크스페이스 버전과 조직 정보에 따라 결정하며, 호출자는 생략할 수 있습니다. |
|
| declaration.business | 임의 JSON 값 | 선택 사항이며, 누락/null은 빈 문자열이 됩니다. 문자열은 앞뒤 공백을 제거하고, 배열/객체/숫자/불리언은 원래 구조를 유지하지 않고 JSON 문자열로 변환됩니다. 예: checkout획득 또는 입력 방법: 비즈니스 소속 식별자를 입력합니다. 소속이 여러 개인 경우 안정적인 문자열 하나를 자체적으로 정하는 것이 좋습니다. |
|
| declaration.{사용자 정의 키} | 임의 JSON 값 | 사용자 정의 속성을 넣을 수 있습니다. 문자열은 그대로 저장되고, 문자열이 아닌 값은 json.dumps로 변환됩니다. JSON 객체/숫자 유형이 유지된다고 의존해서는 안 됩니다. 이후 백그라운드 동기화에서 값/공백이 조정될 수 있습니다. 예: platform획득 또는 입력 방법: 팀에서 합의한 실제 키 이름으로 자리표시자를 교체합니다. 예: costCenter. |
|
| declaration | json | Y | 필수 JSON 객체이며, 객체가 아닌 값은 매개변수 검증 단계에서 거부되어야 합니다. {}는 유효하지만 기존 사용자 정의 키를 삭제하고 시스템 organization 및 business만 다시 생성합니다. 증분 패치가 아닙니다. null 허용: False 예: {"business": "checkout", "costCenter": "platform"}획득 또는 입력 방법: 먼저 현재 선언을 읽고, 여전히 필요한 최상위 비즈니스/사용자 정의 키를 유지한 뒤 공통 보조 declaration을 제거하고 전체를 제출합니다. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/declaration/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"declaration":{"business":"checkout","costCenter":"platform"}}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | boolean | 처리 완료 시 true를 반환합니다. 무료 플랜은 현재 변경 없이 true를 반환하므로 다시 읽어 확인해야 합니다. |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
조직 업스트림 실패는 실제 오류 코드/메시지를 유지할 수 있으며, 이번 응답을 기준으로 합니다. 동적 다운스트림 오류를 고정 매개변수 406으로 위조하지 않습니다. 요청에는 workspaceUUID, 브랜드 또는 Boss 노드 필드가 포함되지 않으며, 이는 현재 워크스페이스에서 결정됩니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 매개변수 파싱 실패 | 매개변수 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 401 | ft.WKSPNotExistOrReleased | 현재 워크스페이스가 존재하지 않거나 해제됨 | 워크스페이스가 존재하지 않음/또는 해제됨 | Key 소유권과 워크스페이스 상태를 확인합니다. |
| 406 | ft.InvalidBossNode | 유료/엔터프라이즈 플랜 조직 노드 구성이 존재하지 않음 | 유효하지 않은 Boss 노드 | 관리자에게 문의하여 조직 사이트 구성을 수정합니다. 호출자는 브랜드/노드 필드를 제출할 필요가 없습니다. |
| 500 | ft.InternalServerError | 조직 업스트림, 스토리지 커밋 또는 캐시 새로 고침 실패 | 내부 오류 | traceId를 보관하고, 먼저 읽어 저장되었는지 확인한 후 재시도 여부를 결정합니다. |
| 400 | ft.JsonFormatError | 요청 JSON의 최상위가 객체가 아님(예: 배열 또는 문자열) | 일부 json 파일 형식 오류 | declaration 객체를 포함하는 JSON 객체를 제출합니다. |