콘텐츠로 이동

워크스페이스 이미지 관련 리소스 업로드



POST /api/v1/workspace/{workspace_uuid}/upload_logo_image

개요

라우트 파라미터로 지정한 워크스페이스에 Logo 또는 사이트 아이콘을 업로드합니다. 성공하면 지정한 언어와 대상 파일명으로 리소스를 저장합니다.

호출 전 준비 및 사용 단계

  1. 워크스페이스 목록에서 대상 워크스페이스 UUID를 가져옵니다. 쓰기 권한이 있는 External API 서명 계정과 5 MiB 이하의 png 또는 ico 파일을 준비합니다.
  2. 대상 파일명과 언어를 선택하고 multipart 예시에 따라 서명하여 업로드합니다. 동일한 워크스페이스, 파일명, 언어로 다시 업로드하면 파일이 교체됩니다.
  3. Logo URL 가져오기로 리소스에 접근할 수 있는지 확인합니다.

예시의 wksp_example은 실제 UUID로 바꾸세요. 업로드 전에 사이트와 워크스페이스 식별자를 확인하세요. 아이콘을 사용할 때는 대상 filename과 로컬 파일을 모두 favicon.ico 또는 실제 .ico 파일로 바꾸세요. 업로드 API는 이미지 형식을 변환하지 않습니다.

라우트 파라미터

파라미터명 타입 필수 설명
workspace_uuid string Y 워크스페이스 UUID
예: wksp_example
가져오기 또는 입력 방법: 워크스페이스 목록 응답의 content.data[*].uuid를 복사합니다.

요청 헤더

파라미터명 타입 필수 설명
X-Df-SVersion string 서명 버전, 아래 예시에서는 v20240417을 사용합니다.
예: v20240417
가져오기 또는 입력 방법: 예시와 동일하게 입력하며, 서명 알고리즘과 대응합니다.
X-Df-Access-Key string Y 요청 AK 정보
예: <access-key>
가져오기 또는 입력 방법: External API 관리자가 할당합니다.
X-Df-Signature string Y 서명 정보
예: <hex-signature>
가져오기 또는 입력 방법: 아래 multipart 예시를 참고하여 Secret Key로 POST, nonce, 원본 경로 및 쿼리 문자열, 타임스탬프, 빈 문자열을 연결한 텍스트에 서명합니다.
X-Df-Timestamp string Y 요청 시 타임스탬프
예: 1785456000
가져오기 또는 입력 방법: 호출 시점의 현재 Unix 초를 입력합니다. 예: date +%s 실행.
X-Df-Nonce string Y 요청 시 생성하는 임시 코드
예: b53b47e12e514616ad8cb1f17cb66dce
가져오기 또는 입력 방법: 매 요청마다 새로운 임의 값을 생성합니다. 예: uuid.uuid4().hex.

Query 요청 파라미터

파라미터명 타입 필수 설명
filename string 파일명
선택 가능 값: ['logo.png', 'favicon.ico']
예: logo.png
가져오기 또는 입력 방법: logo.png 또는 favicon.ico를 선택하며, 생략하면 logo.png입니다.
language string 언어
선택 가능 값: ['zh', 'en', 'zh-hant', 'id', 'ja', 'ko']
예: zh
가져오기 또는 입력 방법: 적용할 언어를 선택하며, 생략하면 zh입니다.

파일 파라미터(multipart/form-data)

파라미터명 타입 필수 설명
file file Y 시스템 logo 등 관련 파일
단일 파일 크기 상한: 5M
파일 수 상한: 1
허용 파일 확장자: ['png', 'ico']
예: logo.png
가져오기 또는 입력 방법: 업로드할 로컬 png 또는 ico 파일을 선택합니다.

파라미터 추가 설명

multipart/form-data의 file 필드로 파일 하나를 업로드합니다. png 또는 ico를 허용하며 상한은 5 MiB입니다. 서버는 요청에서 지정한 filename으로 저장합니다.

filename을 생략하면 logo.png를 사용하고, language를 생략하면 zh를 사용합니다. 저장 후 "이미지 관련 리소스 가져오기" API로 URL을 조회할 수 있습니다. 아래 예시는 v20240417을 사용합니다. 이 업로드 라우트는 먼저 폼을 파싱하며, 서명 원문의 body 부분에는 빈 문자열을 사용하고 타임스탬프 뒤의 공백 하나를 유지합니다. 동일한 요청 안에서 같은 경로, 쿼리 파라미터, nonce, 타임스탬프를 사용하세요.

요청 예시

import hashlib
import hmac
import os
import time
import uuid

import requests

endpoint = os.environ["DF_EXTERNAL_ENDPOINT"].rstrip("/")
full_path = "/api/v1/workspace/wksp_example/upload_logo_image?filename=logo.png&language=zh"
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
to_sign = " ".join(("POST", nonce, full_path, timestamp, ""))
signature = hmac.new(os.environ["DF_EXTERNAL_SECRET_KEY"].encode(), to_sign.encode(), hashlib.sha256).hexdigest()

headers = {
    "X-Df-Access-Key": os.environ["DF_EXTERNAL_ACCESS_KEY"],
    "X-Df-Signature": signature,
    "X-Df-Timestamp": timestamp,
    "X-Df-Nonce": nonce,
    "X-Df-SVersion": "v20240417",
}
with open("logo.png", "rb") as file:
    response = requests.post(endpoint + full_path, headers=headers, files={"file": ("logo.png", file, "image/png")}, timeout=30)
response.raise_for_status()
print(response.json())

응답

HTTP 200, application/json. 동일한 워크스페이스, 대상 파일명, 언어로 다시 업로드하면 해당 파일을 덮어씁니다.

필드 타입 설명
content boolean 저장에 성공하면 true를 반환합니다.
{
    "code": 200,
    "content": true,
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하세요.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.UploadFailed 요청에 업로드 파일이 포함되지 않음 파일이 업로드되지 않았습니다. multipart/form-data로 file을 업로드합니다.
406 ft.ParameterValidationFailed 파일 필드명, 확장자, 수량 또는 크기가 요구 사항을 충족하지 않거나 Query 파라미터가 열거 값에 맞지 않음 메시지에 유효하지 않은 필드 또는 규칙이 표시됩니다. file, png/ico, 단일 파일 5 MiB 및 filename/language의 선택 가능 값을 확인합니다.

문서 평가

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