コンテンツにスキップ

ワークスペース画像関連リソースのアップロード



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

概要

ルートパラメータで指定したワークスペースにロゴまたはサイトアイコンをアップロードします。成功時には、指定された言語と対象ファイル名のリソースが保存されます。

呼び出し前の準備と使用手順

  1. ワークスペース一覧から対象ワークスペースの UUID を取得します。書き込み権限を持つ External API 署名アカウントと、5 MiB 以下の png または ico ファイルを準備します。
  2. 対象ファイル名と言語を選択し、multipart の例に従って署名してアップロードします。同じワークスペース、ファイル名、言語で再度アップロードするとファイルは置き換えられます。
  3. ロゴ 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 の選択可能な値を確認します。

フィードバック

このページは役に立ちましたか?