콘텐츠로 이동

워크스페이스 이미지 업로드



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 파일을 준비하고 경로를 실제 파일로 바꿉니다.

파라미터 추가 설명

유의 사항

  1. 현재 API는 form 요청이며, 파일 내용은 폼 내 file 필드에 저장됩니다.
  2. 한 번의 요청에는 파일 하나만 전달할 수 있습니다.
  3. 업로드한 파일의 원래 이름과 관계없이 최종 저장 시 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를 보존합니다. 덮어쓰기 전에 이전 버전을 보관합니다. 실패 시 일부 파일이 이미 변경되었을 수 있습니다.

문서 평가

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