ワークスペース画像関連リソースのアップロード¶
POST /api/v1/workspace/{workspace_uuid}/upload_logo_image
概要¶
ルートパラメータで指定したワークスペースにロゴまたはサイトアイコンをアップロードします。成功時には、指定された言語と対象ファイル名のリソースが保存されます。
呼び出し前の準備と使用手順¶
- ワークスペース一覧から対象ワークスペースの UUID を取得します。書き込み権限を持つ External API 署名アカウントと、5 MiB 以下の png または ico ファイルを準備します。
- 対象ファイル名と言語を選択し、multipart の例に従って署名してアップロードします。同じワークスペース、ファイル名、言語で再度アップロードするとファイルは置き換えられます。
- ロゴ 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 の例を参照し、POST、nonce、元のパスとクエリ文字列、タイムスタンプ、空文字列を連結したテキストに Secret Key で署名します。 |
| 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 | システムロゴなどの関連ファイル 単一ファイルサイズの上限: 5M ファイル数の上限: 1 許可されるファイル拡張子: ['png', 'ico'] 例: logo.png取得または入力方法: アップロードするローカルの png または ico ファイルを選択します。 |
パラメータ補足説明¶
multipart/form-data の file フィールドを使用して 1 つのファイルをアップロードします。png または ico を許可し、上限は 5 MiB です。サーバーはリクエストで指定された filename に従って保存します。
filename を省略した場合は logo.png、language を省略した場合は zh を使用します。保存後は「画像関連リソースの取得」API で URL を照会できます。
以下の例では v20240417 を使用します。このアップロードルートは先にフォームを解析します。署名対象テキストの body 部分には空文字列を使用し、タイムスタンプの後のスペースを 1 つ保持します。同じリクエスト内で同じパス、クエリパラメータ、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 の選択可能な値を確認します。 |