생성¶
POST /api/v1/workspace/create
개요¶
새 워크스페이스를 생성하며, 소스 워크스페이스의 Owner를 상속하고 동시에 API Key를 생성할 수 있습니다.
호출 전 준비 및 사용 단계¶
소스 워크스페이스에서 workspace.setManage 권한이 있는 API Key를 사용합니다. 현재 워크스페이스를 수정하는 것이 아니라 새 워크스페이스를 생성하는 것이며, 이 페이지의 공개 필드 7개만 제출하고 External/백엔드의 ownerUuid, storageTypeUUID, versionType 등의 파라미터를 적용할 수 없습니다. 기본적으로 소스 워크스페이스의 활성 Owner 계정에서 새 워크스페이스의 Owner를 상속하며, 호출 Key 자체를 Owner로 설정하지 않습니다. 먼저 멤버/콘솔에서 소스 워크스페이스에 로그인 가능한 활성 Owner가 있는지 확인하세요. 소스 Owner가 없거나 비활성화된 경우, 현재 구현은 Owner가 연결되지 않은 워크스페이스를 계속 생성할 수 있으므로 인터페이스가 강제로 거부한다고 의존할 수 없습니다.
사이트 설정이 스토리지 엔진, 기본 버전 및 보존 기간을 결정합니다. SaaS의 기본 free 워크스페이스는 자동으로 쓰기 잠금될 수 있으며, 생성이 즉시 쓰기 가능함을 보장하지 않습니다. createPayWsVersion=true는 SaaS에서만 적용되며, 소스 워크스페이스의 청구 센터 바인딩 정보가 필요합니다. 새 워크스페이스에 동일한 계정을 바인딩하고 pay로 업그레이드하므로 반드시 먼저 과금 영향을 확인해야 합니다.
needCreateAk=true이면 akInfo 평문을 반환하므로 즉시 안전하게 저장하고, 반환된 keySk로 새 워크스페이스에 액세스합니다. 새 Key에 명시적 역할 연결이 없으면 인증은 wsAdmin으로 폴백되며 권한이 없는 것이 아닙니다. 수집 token과 API Key는 혼용할 수 없습니다. 응답의 wsInfo는 생성 단계의 스냅샷이며, tenantId 및 makeResourceExceptionCode 등의 최종 값은 이후 단계에서 변경될 수 있으므로, 새 워크스페이스 Key로 현재 워크스페이스 상세와 실제 스토리지를 읽어 검증해야 합니다.
생성은 멱등하지 않으며, 이름 중복 제거나 전체 프로세스 롤백이 없습니다. 워크스페이스, 수집 Token, 기본 리소스가 먼저 저장된 후 데이터베이스 생성/알림/청구 센터 처리가 진행되므로 실패하더라도 워크스페이스가 이미 존재할 수 있습니다. 소스 워크스페이스 Key로 다른 워크스페이스를 자동 관리할 수 없으며, 응답을 분실한 경우 Owner가 워크스페이스 목록에서 확인한 후 계속 진행하고, 무조건 재시도하지 마세요.
요청 헤더¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| akName | string | 선택 사항이며 기본값은 default이고 needCreateAk=true일 때만 적용됩니다. Key 리소스 UUID가 아니며 역할/권한을 결정하지 않습니다. null 허용: False 예시: automation_admin획득 또는 입력 방법: 새 워크스페이스 자동화 Key의 용도 이름을 지정합니다. |
|
| createPayWsVersion | boolean | 선택 사항이며 기본값은 false입니다. 배포 플랜에서는 이 입력 파라미터를 무시합니다. SaaS에서 true이면 소스 워크스페이스의 청구 센터 계정이 유효해야 하며, 해당 브랜드/정산 노드를 그대로 사용하여 바인딩 및 업그레이드를 수행하므로 과금이 발생할 수 있으니 사전에 확인해야 합니다. false이면 사이트 기본 버전을 사용하며, 항상 동일한 체험 버전임을 보장하지 않습니다. null 허용: False 예시: false획득 또는 입력 방법: SaaS에서 새 워크스페이스를 소스 워크스페이스의 청구 센터 계정에 연결하고 상용 플랜으로 업그레이드해야 할 때 true로 설정하며, 먼저 소스 계정이 바인딩되어 있는지 확인합니다. |
|
| desc | string | 선택 사항이며 생략 시 빈 문자열입니다. null을 허용한다고 선언되어 있으나 저장 컬럼이 비어 있지 않아야 하므로 명시적 문자열을 권장하며 null은 사용하지 마세요. 저장 컬럼은 500자이므로 500자를 넘지 않도록 권장합니다. 빈 문자열 허용: True null 허용: True 예시: 接口文档演示工作空间획득 또는 입력 방법: 새 워크스페이스의 용도, 담당자 등의 설명을 입력합니다. |
|
| language | string | 선택 사항이며 기본값은 zh입니다. 빈 문자열은 그대로 저장되며 자동으로 대체되지 않습니다. null을 허용한다고 선언되어 있으나 데이터베이스가 비어 있지 않아야 하므로 null은 피하세요. 빈 문자열 허용: True null 허용: True 선택 가능한 값: ['zh', 'en', 'zh-hant', 'id', 'ja', 'ko'] 예시: zh획득 또는 입력 방법: 새 워크스페이스에 zh/en/zh-hant/id/ja/ko 중 하나를 선택합니다. |
|
| menuStyle | string | 선택 사항인 레거시 스타일 식별자이며 생략 시 빈 문자열입니다. 현재는 저장만 하며, 메뉴 v3 구성을 생성하거나 실제 권한을 조정하는 것을 의미하지 않습니다. 신규 연동 시에는 생략을 권장합니다. 빈 문자열 허용: True null 허용: False 예시: 획득 또는 입력 방법: 레거시 클라이언트에서 필요할 때 기존 워크스페이스의 menuStyle을 유지합니다. |
|
| name | string | Y | 필수 문자열이며 최대 256자로 선언되어 있으나 저장 컬럼은 128자이므로 128자를 넘지 않도록 권장합니다. 현재 비어 있지 않음을 강제하거나 공백을 자동 제거하지 않습니다. 멱등 키가 아니며 이름으로 중복 제거하지 않습니다. null 허용: False 최대 길이: 256 예시: API示例空间획득 또는 입력 방법: 업무 용도에 따라 이름을 지정하고, 먼저 콘솔에서 대상 워크스페이스가 이미 있는지 확인합니다. |
| needCreateAk | boolean | 선택 사항이며 기본값은 false입니다. true이면 수동 Key 하나를 생성하고 akInfo 평문을 반환합니다. 해당 Key에 명시적 역할 연결이 없으면 실제 인증은 wsAdmin으로 폴백됩니다. false이면 이 akInfo를 반환하지 않으며, 워크스페이스 수집 token을 API Key로 사용할 수 없습니다. null 허용: False 예시: true획득 또는 입력 방법: 이번 생성 응답에서 새 워크스페이스의 사용 가능한 API Key를 얻어야 할 때 true로 설정합니다. |
파라미터 추가 설명¶
새 워크스페이스의 Owner는 호출 측 Key 역할이 아니라 소스 워크스페이스의 활성 Owner를 따릅니다. 예시는 사이트 기본 unlimited 구성 기준이며, 실제 엔진/버전/보존 기간은 생성 응답과 이후 새 워크스페이스 상세를 기준으로 합니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"API示例空间","desc":"接口文档演示工作空间","needCreateAk":true,"akName":"automation_admin","language":"zh","createPayWsVersion":false}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content.accountInfo | array<string> |
새 워크스페이스에 참여한 계정 UUID 배열입니다. 현재 공개 진입점에서는 일반적으로 소스 워크스페이스의 활성 Owner입니다. Owner를 찾지 못하면 비어 있을 수 있으며, 오류 발생을 보장하지 않습니다. |
| content.accountInfo[] | string | 새 워크스페이스에 참여한 계정 UUID입니다. |
| content.ownerInfo | object | 소스 워크스페이스에서 찾은 활성 Owner 요약입니다. 찾지 못하면 세 필드가 빈 문자열일 수 있으며 생성이 계속될 수도 있습니다. |
| content.ownerInfo.name | string | Owner 표시 이름. |
| content.ownerInfo.email | string | Owner 이메일. |
| content.ownerInfo.accountUUID | string | 새 워크스페이스의 Owner로 설정된 계정 UUID입니다. |
| content.akInfo | object | needCreateAk=true일 때만 나타나며, 새 워크스페이스의 수동 API Key 평문이므로 안전하게 저장합니다. |
| content.akInfo.keyId | string | keyAk와 동일한 ak 값이며 레거시 필드 이름입니다. wsak_ 리소스 UUID가 아닙니다. |
| content.akInfo.keyAk | string | 새 Key의 ak 평문입니다. |
| content.akInfo.keySk | string | 새 Key의 sk 평문이며, 해당 새 워크스페이스의 OpenAPI DF-API-KEY로 사용할 수 있습니다. |
| content.akInfo.name | string | 새 Key 이름. |
| content.wsInfo.id | integer | 사이트 내 레코드 일련번호이며, 이후 호출에는 uuid를 사용합니다. |
| content.wsInfo.uuid | string | 워크스페이스 UUID. |
| content.wsInfo.status | integer | 0 정상, 3 삭제 표시됨. 삭제 반환 스냅샷은 3입니다. |
| content.wsInfo.creator | string | 생성 주체 식별자이며, 신규 생성 시 일반적으로 현재 호출 Key 리소스 UUID입니다. |
| content.wsInfo.updator | string | 최근 수정 주체이며, 수정되지 않은 경우 비어 있을 수 있습니다. |
| content.wsInfo.createAt | integer | 생성 시간, Unix 초. |
| content.wsInfo.deleteAt | integer | 삭제 시간, Unix 초, 삭제되지 않은 경우 일반적으로 -1. |
| content.wsInfo.updateAt | integer | 업데이트 시간, Unix 초, 아직 수정되지 않은 경우 일반적으로 -1. |
| content.wsInfo.name | string | 워크스페이스 표시 이름. |
| content.wsInfo.token | string | 워크스페이스 기본 수집 Token입니다. 자격 증명으로 저장해야 하며 OpenAPI의 DF-API-KEY가 아닙니다. 예시는 자리 표시자 값을 사용합니다. |
| content.wsInfo.cliToken | string | 워크스페이스 CLI 자격 증명이며 자격 증명으로 저장합니다. 예시에는 실제 값이 포함되지 않습니다. |
| content.wsInfo.dbUUID | string | 메트릭 데이터베이스 레코드 UUID. |
| content.wsInfo.esInstanceUUID | string | 실제 로그 스토리지 인스턴스 UUID. |
| content.wsInfo.dashboardUUID | string | 워크스페이스 기본 뷰 식별자이며, 설정되지 않은 경우 비어 있습니다. |
| content.wsInfo.exterId | string | 외부 시스템 워크스페이스 식별자이며 일반적으로 비어 있습니다. 이 페이지에서 쓸 수 있는 필드가 아닙니다. |
| content.wsInfo.rpName | string | 메트릭 보존 정책 내부 별칭입니다. durationSet.rp를 대체하는 데 사용하지 마세요. |
| content.wsInfo.desc | string | 워크스페이스 설명. |
| content.wsInfo.durationSet | object 또는 null | 데이터 유형별로 저장된 표준 스토리지 기간이며, 키는 엔진, 버전 및 인덱스 병합 상태에 따라 달라지고 값은 예를 들어 7d입니다. |
| content.wsInfo.storagePolicy | object 또는 null | 데이터 유형별로 저장된 장기 스토리지 정책입니다. 여기의 장기 정책은 표준 durationSet과 구분됩니다. |
| content.wsInfo.datastore | object 또는 null | 데이터 유형별로 저장된 실제 스토리지 엔진이며, 예: metric=guancedb, logging=doris. |
| content.wsInfo.lastDqlDataCheckTime | object 또는 null | 데이터 유형별로 기록된 최근 DQL 데이터 검사 정보이며, 시스템이 유지 관리하는 동적 객체입니다. |
| content.wsInfo.declaration | object 또는 null | 워크스페이스 자체의 조직 및 비즈니스 선언으로 organization, business를 포함할 수 있습니다. 이는 워크스페이스 컬럼이며 외부 공통 선언이 아닙니다. |
| content.wsInfo.esIndexSettings | object 또는 null | 데이터 유형별로 저장된 인덱스 구성 객체입니다. 빈 객체는 워크스페이스 수준 사용자 정의 템플릿이 없음을 의미하며, 다운스트림에 기본 템플릿이 없음을 의미하지는 않습니다. |
| content.wsInfo.bindInfo | object 또는 null | 워크스페이스 브랜드 텍스트, 이메일 및 도메인 재정의 객체이며, 키 정의는 바인딩 정보 설정을 참조하세요. |
| content.wsInfo.versionType | string | 워크스페이스 버전이며, 예: free, freeEdition, pay, enterprise, unlimited. 생성 시 사이트 설정을 따르며, 이 인터페이스는 버전 입력 파라미터를 제공하지 않습니다. |
| content.wsInfo.billingState | string | 과금 상태 식별자이며, 예: free, normal, arrearage, expired, unlimited. |
| content.wsInfo.bossStation | string | 청구 센터 노드 식별자이며, 예: CN, SG 또는 빈 문자열. |
| content.wsInfo.brandKey | string | 워크스페이스 브랜드 식별자. |
| content.wsInfo.enablePublicDataway | integer | 공용 Dataway 허용 여부, 1 사용, 0 사용 안 함. |
| content.wsInfo.isOpenLogMultipleIndex | integer 또는 boolean | 새 로그 다중 인덱스 생성 허용 여부, 1 사용, 0 사용 안 함. 기존 인덱스가 이로 인해 삭제되지는 않습니다. |
| content.wsInfo.esIndexMerged | integer | 인덱스 병합 여부, 1 병합, 0 분리. |
| content.wsInfo.supportJsonMessage | integer | JSON 메시지 지원 표시, 1 사용, 0 사용 안 함. |
| content.wsInfo.isLocked | integer | 워크스페이스 잠금 표시, 1 잠김, 0 잠기지 않음. |
| content.wsInfo.lockMode | string | 잠금 모드이며, 예: none, writeLocked. |
| content.wsInfo.lockAt | integer | 잠금 시간, Unix 초, 설정되지 않은 경우 일반적으로 -1. |
| content.wsInfo.delayDeleteAt | integer | 지연 정리 기준 시각, Unix 초, 정리 대기 흐름이 아닌 경우 일반적으로 -1. |
| content.wsInfo.inviteAudit | integer | 멤버 초대 심사 사용 여부, 1 사용, 0 사용 안 함. |
| content.wsInfo.makeResourceExceptionCode | string | 리소스 초기화 문제 표시이며 비어 있을 수 있습니다. 생성 흐름에서는 content 최상위에도 최신 문제 표시를 반환합니다. |
| content.wsInfo.loggingCutSize | integer | 대용량 로그 분할 단위, 바이트. |
| content.wsInfo.language | string | 워크스페이스 언어 식별자. |
| content.wsInfo.noviceGuide | boolean | 초보자 가이드 표시. |
| content.wsInfo.timezone | string | 워크스페이스 시간대, 설정되지 않은 경우 비어 있습니다. |
| content.wsInfo.menuStyle | string | 메뉴 스타일 식별자, 설정되지 않은 경우 비어 있습니다. |
| content.wsInfo.tenantId | integer | 워크스페이스 테넌트 ID입니다. 생성 응답은 테넌트 ID가 생성되기 전에 스냅샷을 찍으므로 -1일 수 있으며, 이후 상세에서 최종 값을 읽습니다. |
| content.wsInfo.isOpenCustomMappingRule | integer | 사용자 정의 매핑 규칙 스위치, 1 사용, 0 사용 안 함. |
| content.wsInfo.enableRumMultipleTable | integer | RUM 테이블 분할 스위치, 1 사용, 0 사용 안 함. |
| content.wsInfo.enableMFA | boolean | MFA 요구 여부. |
| content.wsInfo.disableQueryAcceleration | integer | 쿼리 가속 비활성화 표시, 1 비활성화, 0 비활성화 안 함. |
| content.wsInfo.disableDataWrite | integer | 쓰기 비활성화 표시, 1 비활성화, 0 비활성화 안 함. |
| content.wsInfo.disableDataWriteAt | integer | 쓰기 금지 시간, Unix 초, 아직 설정되지 않은 경우 일반적으로 -1. |
| content.wsInfo.logBackupQueryTimeLimit | integer | 백업 로그 쿼리 시간 범위 제한 값, 단위 시간. |
| content.wsInfo.engineSetting | object | 엔진 전용 구성 동적 객체이며, 레거시 nodegroup 필드는 출력에서 node_group으로 정규화됩니다. |
| content.wsInfo.enableAI | boolean | 워크스페이스 AI 전체 스위치. |
| content.wsInfo.enableAPIKeySecurityDisplayPolicy | boolean | API Key 보안 표시 정책 스위치. |
| content.wsInfo.enableObsyAISubscriptionBilling | boolean | Obsy AI 구독 과금 스위치. |
| content.wsInfo.tokenIpSet | object 또는 null | 워크스페이스 Token의 IP 액세스 제한 구성 동적 객체입니다. 이 페이지에서는 반환만 하며, 이 요청 파라미터로는 수정할 수 없습니다. |
| content.wsInfo.singleConfig | object 또는 null | 워크스페이스 기능 구성 동적 객체입니다. 워크스페이스에 이미 있는 구성을 기준으로 하며, 여기서 고정된 구성 키를 보장하지 않습니다. |
| content.wsInfo.issueUpgrade | boolean | 인시던트 업그레이드 기능 스위치. |
| content.wsInfo.durationSet.{데이터 유형} | string | 해당 데이터 유형의 표준 보존 기간이며, 예: rp, logging, keyevent, tracing, rum, apm, network, backup_log. 현재 구성에 따라 다른 읽기 전용 키가 있을 수 있습니다. |
| content.wsInfo.storagePolicy.{데이터 유형} | object | 해당 유형의 장기 정책이며, 주로 rp, logging을 사용합니다. |
| content.wsInfo.storagePolicy.{데이터 유형}.longStorageEnabled | boolean | 장기 스토리지 사용 여부. |
| content.wsInfo.storagePolicy.{데이터 유형}.longStorageDuration | string | 장기 총 보존 기간이며, 예: 180d. 비활성화 후에는 일반적으로 빈 문자열입니다. |
| content.wsInfo.datastore.{데이터 유형} | string | 해당 유형에서 사용하는 엔진 이름이며, 예: es, doris, scopedb, volctls, sls, guancedb. 인스턴스 UUID가 아닙니다. |
| content.wsInfo.declaration.organization | string | 조직 이름이며, 선언 구성이 있을 때 제공됩니다. |
| content.wsInfo.declaration.business | string | 비즈니스 설명이며, 선언 구성이 있을 때 제공됩니다. |
| content.wsInfo.esIndexSettings.{데이터 유형} | object | 해당 유형의 인덱스 설정. |
| content.wsInfo.esIndexSettings.{데이터 유형}.number_of_shards | integer | 기본 샤드 수이며, 표시 여부는 엔진에 따라 다릅니다. |
| content.wsInfo.esIndexSettings.{데이터 유형}.number_of_replicas | integer | 복제본 수. |
| content.wsInfo.esIndexSettings.{데이터 유형}.rollover_max_size | integer | 샤드 롤오버 임계값이며, 인터페이스가 엔진 정의에 따라 그대로 전달합니다. |
| content.wsInfo.esIndexSettings.{데이터 유형}.hot_retention | integer | 핫 데이터 보존 기간, 시간. |
| content.wsInfo.esIndexSettings.{데이터 유형}.cold_retention | integer | 선택적 콜드 데이터 보존 기간, 시간. |
| content.wsInfo.esIndexSettings.{데이터 유형}.archive_retention | integer | 선택적 아카이브 데이터 보존 기간, 시간. |
| content.wsInfo.esIndexSettings.{데이터 유형}.openAdvancedConfig | integer | 고급 구성 표시, 일반적으로 0 또는 1. |
| content.wsInfo.engineSetting.node_group | string | 선택적 엔진 노드 그룹 식별자이며, 기타 구성 항목은 해당 엔진이 결정합니다. |
| content.wsInfo.bindInfo.{구성 항목} | JSON 값 | 기존 브랜드 재정의 값이며, 키 의미는 바인딩 정보 설정 인터페이스를 기준으로 합니다. |
| content.wsInfo.lastDqlDataCheckTime.{데이터 유형} | JSON 값 | 해당 유형의 시스템 유지 관리 검사 값이며, 쿼리 결과가 아닙니다. |
| content.wsInfo.tokenIpSet.{구성 항목} | JSON 값 | 기존 Token IP 정책이며, 읽은 후 그 구조를 유지하고 이를 근거로 OpenAPI 인증 헤더를 구성하지 않습니다. |
| content.wsInfo.singleConfig.{구성 항목} | JSON 값 | 기존 기능 구성 값이며, 구체적인 타입과 키는 해당 기능 구성 규약에 따릅니다. |
| content.makeResourceExceptionCode | string | 빈 문자열 또는 noPermissionCreateProject/addDataStoreFailure입니다. SLS/TLS 일부 데이터베이스 생성 스토리지 문제에 이 표시를 사용하며, 모든 실패 유형을 포괄하지는 않습니다. |
| content.declaration | object 또는 null | 응답 공통 선언입니다. 새 워크스페이스 자체의 조직 정보는 content.wsInfo.declaration을 기준으로 합니다. |
{
"code": 200,
"content": {
"accountInfo": [
"acnt_owner_example"
],
"ownerInfo": {
"name": "示例Owner",
"email": "xxx@guance.com",
"accountUUID": "acnt_owner_example"
},
"akInfo": {
"keyId": "<CREATED-AK>",
"keyAk": "<CREATED-AK>",
"keySk": "<CREATED-SK>",
"name": "automation_admin"
},
"wsInfo": {
"id": 1001,
"uuid": "wksp_created_example",
"status": 0,
"creator": "wsak_source",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"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
},
"makeResourceExceptionCode": "",
"declaration": {}
},
"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.InvalidBrandKey | 사이트 기본 브랜드가 허용 집합에 없음 | 브랜드 식별자{}가 유효하지 않습니다. |
관리자에게 사이트 브랜드 구성을 확인하도록 요청합니다. |
| 400 | ft.InvalidWorkspace | SaaS 유료 생성 시 소스 워크스페이스 사용 불가 | 유효하지 않은 워크스페이스: {} | 소스 워크스페이스가 유효한지 확인합니다. |
| 400 | ft.InvalidActionSourceNoBindBossAccount | SaaS 유료 생성을 요청했으나 소스 워크스페이스에 유효한 청구 센터 계정이 바인딩되지 않음 | 유효하지 않은 작업, 소스 워크스페이스에 Boss 계정이 바인딩되어 있지 않습니다 | 먼저 소스 워크스페이스의 청구 센터 바인딩을 완료하고 과금을 확인합니다. |
| 404 | ft.NoExistsTimeDbInstance | 사용 가능한 기본 시계열 스토리지 인스턴스 없음 | 시계열 데이터베이스 구성을 찾을 수 없습니다 | 관리자에게 사이트 스토리지 구성을 보완하도록 요청합니다. |
| 404 | ft.NamespaceDatastoreNotFound | 사이트 기본 데이터 유형에 사용 가능한 스토리지 엔진 없음 | {}의 스토리지 유형을 찾을 수 없습니다 | 관리자가 네임스페이스 구성을 확인합니다. |
| 406 | ft.CurrentVersionUnsupportRp | 기본 버전의 보존 기간으로 유효한 구성을 형성할 수 없음 | 현재 버전은 rp:{}를 지원하지 않습니다 |
관리자가 기본 버전과 보존 기간을 확인합니다. |
| 400 | ft.ErrorBindCcAccount | 워크스페이스가 생성된 후 청구 센터 계정 바인딩 실패 | 【청구 센터 계정】바인딩 실패 | 먼저 워크스페이스 존재 및 바인딩 상태를 확인하고, 완료되지 않은 단계만 처리합니다. |
| 400 | ft.ErrorBindCcSettlementMethod | 청구 센터 결제 방식 바인딩 실패 | 【청구 센터 결제 방식】바인딩 실패 | 워크스페이스와 청구 센터의 현재 상태를 확인하고 워크스페이스 중복 생성을 피합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시/큐, 다운스트림 일반 5xx/타임아웃 또는 처리되지 않은 유형의 실패; 쓰기가 이미 커밋되었을 수 있음 | 내부 오류 | 먼저 현재/대상 워크스페이스 상세와 다운스트림 상태에서 저장된 결과를 확인하고, 무작정 재생성/로테이션하지 마세요. 이미 저장된 경우 완료되지 않은 동기화만 처리하고 traceId를 제공합니다. |
| 406 | ft.InvalidBossNode | SaaS 유료 생성 사전 조회 또는 이후 청구 센터 처리에 브랜드/노드 구성이 필요하나 유효한 노드가 없음 | 유효하지 않은 Boss 노드 | 관리자에게 브랜드와 청구 센터 노드를 확인하도록 요청합니다. 최초 사전 단계 실패 시에는 아직 생성되지 않았지만, 이후 단계의 동일 실패는 워크스페이스가 이미 존재할 수 있으므로 먼저 현재 상태를 조회해야 합니다. |