콘텐츠로 이동

수정



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를 제공하십시오.

문서 평가

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