워크스페이스 이미지 업로드¶
POST /api/v1/workspace/upload_logo_image
개요¶
현재 워크스페이스의 지정 언어에 대한 로고 또는 브라우저 아이콘을 업로드하고 덮어씁니다.
호출 전 및 사용 단계¶
현재 워크스페이스에서 workspace.setManage 권한이 있는 OpenAPI Key를 사용합니다. 적용 범위는 현재 Key가 속한 워크스페이스이며, Body에 다른 workspaceUUID를 전달하는 것은 지원하지 않습니다.
multipart/form-data를 사용하고 파일 필드명은 file입니다. filename과 language는 URL Query에 둡니다. filename은 대상 용도(logo.png 또는 favicon.ico)를 결정하며 업로드 원본 파일명이 아닙니다. language는 독립 언어 버전을 결정하며 생략 시 zh입니다. 업로드하는 원본 파일은 확장자 png/ico와 크기만 검증하며, 최대 1개, 5MiB이고 이미지 실제 내용을 검사하지 않으며 트랜스코딩도 하지 않습니다. 호출자는 콘텐츠 형식이 대상 파일과 일치하는지 확인해야 합니다.
동일한 워크스페이스/대상 이름/언어로 다시 업로드하면 바로 덮어쓰므로, 롤백하려면 이전 파일을 미리 보관해야 합니다. 다른 언어 또는 다른 용도의 파일은 삭제하지 않습니다. 성공 시 true를 반환하며 URL은 반환하지 않습니다. 현재 워크스페이스의 content.logoUrl/faviconUrl에서 접근 언어에 따라 선택된 실제 유효 주소를 읽을 수 있습니다. language 업로드는 워크스페이스 기본 언어를 수정하지 않습니다. 상세 정보는 약 60초 캐시되며 현재 캐시 키가 언어를 구분하지 않으므로 언어를 전환해도 URL이 즉시 변경된다고 보장하지 않습니다. 페이지/브라우저/CDN에 캐시가 있을 수 있으므로 HTTP 성공이 모든 노드의 표시가 새로고침되었음을 의미하지는 않습니다. 파일 쓰기는 파일 시스템 작업이며, 실패 시 데이터베이스식 롤백을 제공하지 않습니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Query 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| filename | string | 선택 가능한 고정 대상 파일명이며 기본값은 logo.png입니다. 두 값만 허용합니다. 업로드 파일의 원래 이름으로 용도를 결정하지 않습니다. 선택 가능한 값: ['logo.png', 'favicon.ico'] 예시: logo.png가져오기 또는 입력 방법: 로고에는 logo.png, 브라우저 아이콘에는 favicon.ico를 사용합니다. |
|
| language | string | 선택 사항이며 기본값은 zh입니다. 언어별로 독립 저장되며, 생략해도 모든 언어가 동시에 업데이트되지는 않습니다. 선택 가능한 값: ['zh', 'en', 'zh-hant', 'id', 'ja', 'ko'] 예시: zh가져오기 또는 입력 방법: zh/en/zh-hant/id/ja/ko 중에서 선택하며, 접근하는 쪽의 언어와 같아야 합니다. |
파일 파라미터(multipart/form-data)¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| file | file | Y | 필수 단일 파일이며, 원본 파일 확장자는 png 또는 ico(대소문자 정규화)이고 최대 5×1024×1024바이트입니다. Base64 또는 파일 경로 JSON이 아닌 파일 스트림을 전송합니다. 허용 파일 확장자: ['png', 'ico'] 단일 파일 크기 상한: 5M 파일 수 상한: 1 예시: @./company-logo.png가져오기 또는 입력 방법: 로컬에서 유효한 로고/ICO 파일을 준비하고 경로를 실제 파일로 바꿉니다. |
파라미터 추가 설명¶
유의 사항¶
- 현재 API는 form 요청이며, 파일 내용은 폼 내 file 필드에 저장됩니다.
- 한 번의 요청에는 파일 하나만 전달할 수 있습니다.
- 업로드한 파일의 원래 이름과 관계없이 최종 저장 시 filename 파라미터로 지정한 파일명으로 저장됩니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/upload_logo_image?filename=logo.png&language=zh' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-F 'file=@./company-logo.png'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | boolean | 파일이 기록되면 true를 반환하며, 미디어 콘텐츠나 주소는 반환하지 않습니다. |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 406 | ft.UploadFailed | 라우트에서 가져온 file이 비어 있음(일반적인 파일 누락은 선언 검증에서 먼저 거부됨) | 파일이 업로드되지 않음 | multipart 필드 file을 사용하고 유효한 파일 하나를 선택합니다. |
| 500 | ft.InternalServerError | 디렉터리 생성, 파일 저장 또는 후속 응답 처리 실패 | 내부 오류 | 파일이 기록되었는지 및 권한/디스크를 확인하고 traceId를 보존합니다. 덮어쓰기 전에 이전 버전을 보관합니다. 실패 시 일부 파일이 이미 변경되었을 수 있습니다. |