이미지 관련 리소스 가져오기¶
POST /api/v1/workspace/{workspace_uuid}/get_logo_url
개요¶
지정된 워크스페이스, 파일 이름 및 언어에 해당하는 Logo 또는 사이트 아이콘 URL을 가져옵니다. 리소스가 존재하지 않으면 빈 문자열을 반환합니다.
호출 전 및 사용 단계¶
- 워크스페이스 읽기 권한이 있는 External API 서명 계정을 사용하여 워크스페이스 목록 응답의 content.data[*].uuid에서 워크스페이스 UUID를 가져옵니다.
- 업로드 시 사용한 파일 이름과 언어로 조회하며, 두 항목을 생략하면 기본값을 사용합니다. POST에는 요청 본문이 없습니다. 서명 설명에 따라 서명을 계산합니다.
- 빈 URL이 반환되면 워크스페이스, 파일 이름 및 언어를 확인하고 해당 파일이 업로드되었는지 확인합니다. 조회는 리소스를 기록하지 않습니다.
경로 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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>가져오기 또는 입력 방법: POST, nonce, 요청 경로 및 원본 쿼리 문자열, 타임스탬프, 빈 body 순서로 연결한 후 Secret Key로 HMAC-SHA256을 수행하여 16진수 결과를 사용합니다. |
| 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입니다. |
|
| language | string | 언어 선택 가능한 값: ['zh', 'en', 'zh-hant', 'id', 'ja', 'ko'] 예시: zh가져오기 또는 입력 방법: 업로드 시 사용한 언어를 입력하며, 생략 시 zh입니다. 리소스가 존재하지 않아도 다른 언어로 전환되지 않습니다. |
요청 예시¶
import hashlib
import hmac
import os
import time
import uuid
import requests
endpoint = os.environ["DF_EXTERNAL_ENDPOINT"].rstrip("/")
path = "/api/v1/workspace/wksp_example/get_logo_url?filename=logo.png&language=zh"
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
to_sign = " ".join(("POST", nonce, path, timestamp, ""))
signature = hmac.new(os.environ["DF_EXTERNAL_SECRET_KEY"].encode(), to_sign.encode(), hashlib.sha256).hexdigest()
response = requests.post(endpoint + path, 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",
}, timeout=30)
response.raise_for_status()
print(response.json()["content"]["url"])
응답¶
HTTP 200, application/json.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.url | string | 리소스 URL이며, 해당 워크스페이스, 파일 이름 및 언어에 대응하는 파일이 없으면 빈 문자열입니다. |
{
"code": 200,
"content": {
"url": "https://static.example.com/logo/wksp_example_logo.png"
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
{"code":200,"content":{"url":""},"errorCode":"","message":"","success":true,"traceId":"TRACE-EXAMPLE"}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
리소스가 없는 경우는 성공 응답으로 처리됩니다. 인증, 서명, 속도 제한 및 요청 검증 오류는 공통 오류 정의에 따라 처리됩니다.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | filename 또는 language가 허용 범위를 벗어남 | 메시지에 열거형 검증에 실패한 필드가 표시됩니다. | 파라미터 표에 나열된 파일 이름과 언어를 사용합니다. |