수정¶
POST /api/v1/workspace/modify
개요¶
현재 워크스페이스의 이름과 설명을 수정합니다.
호출 전 및 사용 단계¶
workspace.setManage 권한이 있는 현재 워크스페이스 API Key를 사용합니다. name/desc만 지원하며, 백엔드의 전체 워크스페이스 설정을 되돌려 보내는 방식은 지원하지 않습니다. 생략하면 해당 값이 유지됩니다. {}를 전달해도 시간이 갱신되고 캐시가 새로 고쳐지므로, 엄밀히 말해 아무 작업도 하지 않는 것은 아닙니다.
이름 변경은 먼저 데이터베이스에 저장한 다음, 워크스페이스 버전/청구 센터 설정에 따라 청구 센터 이름을 동기화하고 워크스페이스 권한 부여 내 이름을 비동기로 갱신한 뒤 캐시를 새로 고칩니다. 이후 실패가 발생하면 새 이름은 이미 저장되었는데 다른 시스템은 여전히 이전 이름일 수 있습니다. 먼저 워크스페이스 이름을 다시 읽어 확인하고 관리자가 청구 센터/권한 부여 동기화를 점검한 뒤, 실패한 부분을 처리해야 합니다. 성공했다고 해서 모든 비동기 노드에 새 이름이 즉시 표시되는 것은 아닙니다.
응답은 워크스페이스 엔터티이며, 현재 워크스페이스 상세 API의 모든 추가 통계나 change_data를 포함하지 않습니다. 반환된 uuid로 대상을 확인하십시오. 기본 수집 token/cliToken 등 필드는 여전히 민감한 자격 증명이므로 응답 전체를 기록하지 마십시오.
요청 헤더¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>획득 또는 입력 방식: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Body 요청 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| desc | string | 선택적 문자열이며, 생략하면 유지되고 빈 문자열이면 비웁니다. null은 허용되지 않으며, 저장 컬럼은 500자이므로 500자를 넘지 않도록 권장합니다. 빈 문자열 허용: True null 허용: False 예: 更新后的空间用途说明획득 또는 입력 방식: 먼저 현재 워크스페이스 content.desc에서 현재 값을 읽습니다. |
|
| name | string | 선택적 문자열이며, 생략하면 유지됩니다. 선언된 최대 길이는 256자이지만 저장 컬럼은 128자이므로 128자를 넘지 않도록 권장합니다. 현재 비어 있지 않음이 강제되지는 않으며, 빈 문자열은 이름을 비울 수 있으므로 권장하지 않습니다. null 허용: False 최대 길이: 256 예: API示例空间新名称획득 또는 입력 방식: 먼저 현재 워크스페이스 content.name에서 현재 값을 읽습니다. |
파라미터 추가 설명¶
수정 범위는 name과 desc뿐이며, 전체 워크스페이스 상세를 요청 본문으로 사용해서는 안 됩니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"API示例空间新名称","desc":"更新后的空间用途说明"}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content.id | integer | 사이트 내 레코드 일련번호이며, 이후 호출에는 uuid를 사용합니다. |
| content.uuid | string | 워크스페이스 UUID입니다. |
| content.status | integer | 0은 정상, 3은 삭제 표시됨이며, 삭제 시 반환되는 스냅샷은 3입니다. |
| content.creator | string | 생성 주체 식별자이며, 신규 생성 시 보통 현재 호출 Key 리소스 UUID입니다. |
| content.updator | string | 최근 수정 주체이며, 수정되지 않은 경우 비어 있을 수 있습니다. |
| content.createAt | integer | 생성 시간, Unix 초. |
| content.deleteAt | integer | 삭제 시간, Unix 초, 삭제되지 않은 경우 보통 -1입니다. |
| content.updateAt | integer | 업데이트 시간, Unix 초, 아직 수정되지 않은 경우 보통 -1입니다. |
| content.name | string | 워크스페이스 표시 이름입니다. |
| content.token | string | 워크스페이스 기본 수집 Token입니다. 자격 증명으로 보관해야 하며 OpenAPI의 DF-API-KEY가 아닙니다. 예시는 자리 표시자 값을 사용합니다. |
| content.cliToken | string | 워크스페이스 CLI 자격 증명이며 자격 증명으로 보관해야 합니다. 예시에는 실제 값이 포함되어 있지 않습니다. |
| content.dbUUID | string | 메트릭 데이터베이스 레코드 UUID입니다. |
| content.esInstanceUUID | string | 실제 로그 저장 인스턴스 UUID입니다. |
| content.dashboardUUID | string | 워크스페이스 기본 뷰 식별자이며, 설정되지 않은 경우 비어 있습니다. |
| content.exterId | string | 외부 시스템 워크스페이스 식별자이며 보통 비어 있습니다. 이 페이지에서 쓸 수 있는 필드가 아닙니다. |
| content.rpName | string | 메트릭 보존 정책 내부 별칭이며, durationSet.rp를 대체하는 용도로 사용해서는 안 됩니다. |
| content.desc | string | 워크스페이스 설명입니다. |
| content.durationSet | object 또는 null | 데이터 유형별로 저장된 표준 저장 기간이며, 키는 엔진, 버전 및 인덱스 병합 상태에 따라 달라지고 값은 예를 들어 7d입니다. |
| content.storagePolicy | object 또는 null | 데이터 유형별로 저장된 장기 저장 정책이며, 여기의 장기 정책은 표준 durationSet과 구분됩니다. |
| content.datastore | object 또는 null | 데이터 유형별로 저장된 실제 저장 엔진이며, 예를 들어 metric=guancedb, logging=doris입니다. |
| content.lastDqlDataCheckTime | object 또는 null | 데이터 유형별로 기록된 최근 DQL 데이터 검사 정보이며, 시스템이 유지 관리하는 동적 객체입니다. |
| content.declaration | object 또는 null | 워크스페이스 자체의 조직 및 비즈니스 선언이며 organization, business를 포함할 수 있습니다. 이것은 워크스페이스 컬럼이며 외부 공통 선언이 아닙니다. |
| content.esIndexSettings | object 또는 null | 데이터 유형별로 저장된 인덱스 설정 객체이며, 빈 객체는 워크스페이스 수준 사용자 정의 템플릿이 없음을 의미하고 다운스트림에 기본 템플릿이 없다는 뜻은 아닙니다. |
| content.bindInfo | object 또는 null | 워크스페이스 브랜드 텍스트, 메일 및 도메인 재정의 객체이며, 키 정의는 바인딩 정보 설정을 참고하십시오. |
| content.versionType | string | 워크스페이스 버전이며, 예를 들어 free, freeEdition, pay, enterprise, unlimited입니다. 생성 시 사이트 설정을 따르며, 이 API는 버전 입력 파라미터를 제공하지 않습니다. |
| content.billingState | string | 과금 상태 식별자이며, 예를 들어 free, normal, arrearage, expired, unlimited입니다. |
| content.bossStation | string | 청구 센터 노드 식별자이며, 예를 들어 CN, SG 또는 빈 문자열입니다. |
| content.brandKey | string | 워크스페이스 브랜드 식별자입니다. |
| content.enablePublicDataway | integer | 공용 Dataway 허용 여부, 1은 활성화, 0은 비활성화입니다. |
| content.isOpenLogMultipleIndex | integer 또는 boolean | 로그 다중 인덱스 신규 생성 허용 여부, 1은 활성화, 0은 비활성화이며, 기존 인덱스가 이로 인해 삭제되지는 않습니다. |
| content.esIndexMerged | integer | 인덱스 병합 여부, 1은 병합, 0은 분리입니다. |
| content.supportJsonMessage | integer | JSON 메시지 지원 표시, 1은 활성화, 0은 비활성화입니다. |
| content.isLocked | integer | 워크스페이스 잠금 표시, 1은 잠김, 0은 잠기지 않음입니다. |
| content.lockMode | string | 잠금 모드이며, 예를 들어 none, writeLocked입니다. |
| content.lockAt | integer | 잠금 시간, Unix 초이며 설정되지 않은 경우 보통 -1입니다. |
| content.delayDeleteAt | integer | 지연 정리 기준 시점, Unix 초이며 정리 대기 중이 아닌 경우 보통 -1입니다. |
| content.inviteAudit | integer | 멤버 초대 검토 활성화 여부, 1은 활성화, 0은 비활성화입니다. |
| content.makeResourceExceptionCode | string | 리소스 초기화 문제 표시이며 비어 있을 수 있습니다. 생성 흐름에서는 content 최상위에도 최신 문제 표시가 반환됩니다. |
| content.loggingCutSize | integer | 대용량 로그 분할 단위, 바이트. |
| content.language | string | 워크스페이스 언어 식별자입니다. |
| content.noviceGuide | boolean | 초보자 가이드 표시입니다. |
| content.timezone | string | 워크스페이스 시간대이며, 설정되지 않은 경우 비어 있습니다. |
| content.menuStyle | string | 메뉴 스타일 식별자이며, 설정되지 않은 경우 비어 있습니다. |
| content.tenantId | integer | 워크스페이스 테넌트 ID이며, 생성 응답은 테넌트 ID 생성 전에 스냅샷을 캡처하므로 -1일 수 있고 이후 상세에서 최종 값을 읽어야 합니다. |
| content.isOpenCustomMappingRule | integer | 사용자 정의 매핑 규칙 스위치, 1은 활성화, 0은 비활성화입니다. |
| content.enableRumMultipleTable | integer | RUM 테이블 분리 스위치, 1은 활성화, 0은 비활성화입니다. |
| content.enableMFA | boolean | MFA 요구 여부입니다. |
| content.disableQueryAcceleration | integer | 쿼리 가속 비활성화 표시, 1은 비활성화, 0은 비활성화 안 함입니다. |
| content.disableDataWrite | integer | 쓰기 비활성화 표시, 1은 비활성화, 0은 비활성화 안 함입니다. |
| content.disableDataWriteAt | integer | 쓰기 금지 시간, Unix 초이며 아직 설정되지 않은 경우 보통 -1입니다. |
| content.logBackupQueryTimeLimit | integer | 백업 로그 조회 기간 제한 값, 단위는 시간입니다. |
| content.engineSetting | object | 엔진 전용 설정 동적 객체이며, 과거 nodegroup 필드는 출력에서 node_group으로 정규화됩니다. |
| content.enableAI | boolean | 워크스페이스 AI 전체 스위치입니다. |
| content.enableAPIKeySecurityDisplayPolicy | boolean | API Key 보안 표시 정책 스위치입니다. |
| content.enableObsyAISubscriptionBilling | boolean | Obsy AI 구독 과금 스위치입니다. |
| content.tokenIpSet | object 또는 null | 워크스페이스 Token의 IP 액세스 제한 설정 동적 객체이며, 이 페이지에서는 조회만 반환하고 이 요청 파라미터로는 수정할 수 없습니다. |
| content.singleConfig | object 또는 null | 워크스페이스 기능 설정 동적 객체이며, 워크스페이스에 이미 있는 설정을 기준으로 하며 여기서 고정된 설정 키를 보장하지 않습니다. |
| content.issueUpgrade | boolean | 인시던트 에스컬레이션 기능 스위치입니다. |
| content.durationSet.{데이터 유형} | string | 해당 데이터 유형의 표준 보존 기간이며, 예를 들어 rp, logging, keyevent, tracing, rum, apm, network, backup_log입니다. 현재 설정에 따라 다른 읽기 전용 키가 있을 수 있습니다. |
| content.storagePolicy.{데이터 유형} | object | 해당 유형의 장기 정책이며, 주로 rp, logging을 사용합니다. |
| content.storagePolicy.{데이터 유형}.longStorageEnabled | boolean | 장기 저장 활성화 여부입니다. |
| content.storagePolicy.{데이터 유형}.longStorageDuration | string | 장기 총 보존 기간이며, 예를 들어 180d입니다. 비활성화 후에는 보통 빈 문자열입니다. |
| content.datastore.{데이터 유형} | string | 해당 유형이 사용하는 엔진 이름이며, 예를 들어 es, doris, scopedb, volctls, sls, guancedb입니다. 인스턴스 UUID가 아닙니다. |
| content.declaration.organization | string | 조직 이름이며, 선언 설정이 있는 경우 제공됩니다. |
| content.declaration.business | string | 비즈니스 설명이며, 선언 설정이 있는 경우 제공됩니다. |
| content.esIndexSettings.{데이터 유형} | object | 해당 유형의 인덱스 설정입니다. |
| content.esIndexSettings.{데이터 유형}.number_of_shards | integer | 기본 샤드 수이며, 표시 여부는 엔진에 따라 다릅니다. |
| content.esIndexSettings.{데이터 유형}.number_of_replicas | integer | 복제본 수입니다. |
| content.esIndexSettings.{데이터 유형}.rollover_max_size | integer | 샤드 롤오버 임계값이며, API는 엔진 정의에 따라 그대로 전달합니다. |
| content.esIndexSettings.{데이터 유형}.hot_retention | integer | 핫 데이터 보존 기간, 시간. |
| content.esIndexSettings.{데이터 유형}.cold_retention | integer | 선택적 콜드 데이터 보존 기간, 시간. |
| content.esIndexSettings.{데이터 유형}.archive_retention | integer | 선택적 아카이브 데이터 보존 기간, 시간. |
| content.esIndexSettings.{데이터 유형}.openAdvancedConfig | integer | 고급 설정 표시, 보통 0 또는 1입니다. |
| content.engineSetting.node_group | string | 선택적 엔진 노드 그룹 식별자이며, 그 외 설정 항목은 해당 엔진이 결정합니다. |
| content.bindInfo.{설정 항목} | JSON 값 | 기존 브랜드 재정의 값이며, 키 의미는 바인딩 정보 설정 API를 기준으로 합니다. |
| content.lastDqlDataCheckTime.{데이터 유형} | JSON 값 | 해당 유형의 시스템 유지 관리 검사 값이며, 쿼리 결과가 아닙니다. |
| content.tokenIpSet.{설정 항목} | JSON 값 | 기존 Token IP 정책이며, 읽은 후 그 구조를 유지하고 이를 근거로 OpenAPI 인증 헤더를 구성하지 않습니다. |
| content.singleConfig.{설정 항목} | JSON 값 | 기존 기능 설정 값이며, 구체적인 타입과 키는 해당 기능 설정 규약을 따릅니다. |
{
"code": 200,
"content": {
"id": 1001,
"uuid": "wksp_example",
"status": 0,
"creator": "wsak_source",
"updator": "wsak_source",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": 1785427300,
"name": "API示例空间新名称",
"token": "<workspace-token>",
"cliToken": "<workspace-cli-token>",
"dbUUID": "ifdb_example001",
"esInstanceUUID": "esinst_example001",
"dashboardUUID": "",
"exterId": "",
"rpName": "",
"desc": "接口文档演示工作空间",
"durationSet": {
"rp": "7d",
"logging": "7d",
"keyevent": "7d",
"tracing": "7d",
"rum": "7d",
"network": "1d"
},
"storagePolicy": {},
"datastore": {
"metric": "guancedb",
"logging": "doris",
"keyevent": "doris",
"tracing": "doris",
"rum": "doris",
"network": "doris",
"lineage": "doris"
},
"lastDqlDataCheckTime": {},
"declaration": {},
"esIndexSettings": {},
"bindInfo": {},
"versionType": "unlimited",
"billingState": "normal",
"bossStation": "",
"brandKey": "guance",
"enablePublicDataway": 1,
"isOpenLogMultipleIndex": 1,
"esIndexMerged": 0,
"supportJsonMessage": 1,
"isLocked": 0,
"lockMode": "none",
"lockAt": -1,
"delayDeleteAt": -1,
"inviteAudit": 0,
"makeResourceExceptionCode": "",
"loggingCutSize": 10240,
"language": "zh",
"noviceGuide": false,
"timezone": "",
"menuStyle": "",
"tenantId": -1,
"isOpenCustomMappingRule": 0,
"enableRumMultipleTable": 1,
"enableMFA": false,
"disableQueryAcceleration": 0,
"disableDataWrite": 0,
"disableDataWriteAt": -1,
"logBackupQueryTimeLimit": 24,
"engineSetting": {},
"enableAI": false,
"enableAPIKeySecurityDisplayPolicy": false,
"enableObsyAISubscriptionBilling": false,
"tokenIpSet": {},
"singleConfig": {},
"issueUpgrade": true
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.
청구 센터 호출이 필요한 경우, 명확한 업스트림 4xx는 실제 HTTP 및 ft.CloudCareApiError를 유지할 수 있으며 message는 업스트림 비즈니스 안내를 따릅니다. 일반적인 5xx/타임아웃은 최종적으로 500 ft.InternalServerError로 통일됩니다. 먼저 워크스페이스의 저장된 상태와 청구 센터 결과를 확인하고, 실패를 근거로 곧바로 다시 생성하지 마십시오.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방식 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 타입 및 값을 확인하십시오. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하십시오. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 이 페이지의 파라미터에 따라 JSON 객체를 제출하십시오. |
| 406 | ft.NotFoundWorkspace | 현재 워크스페이스가 존재하지 않음/활성 조건을 충족하지 않음 | 지정된 워크스페이스를 찾을 수 없음 | 현재 Key에 대응하는 워크스페이스 상태를 확인하십시오. |
| 406 | ft.InvalidBossNode | 청구 센터 동기화가 필요하지만 사이트 브랜드/노드가 설정되지 않음 | 유효하지 않은 Boss 노드 | 관리자가 청구 센터 노드를 확인해야 하며, 워크스페이스 이름은 이미 저장되었을 수 있습니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시/큐, 다운스트림 일반 5xx/타임아웃 또는 처리되지 않은 유형의 실패; 쓰기가 이미 커밋되었을 수 있음 | 내부 오류 | 먼저 현재/대상 워크스페이스 상세와 다운스트림 상태에서 저장된 결과를 확인하고, 무작정 재생성/로테이션하지 마십시오. 이미 저장되었다면 완료되지 않은 동기화만 처리하고 traceId를 제공하십시오. |