ワークスペース画像のアップロード¶
POST /api/v1/workspace/upload_logo_image
概要¶
現在のワークスペースにおいて、指定した言語の Logo またはブラウザアイコンをアップロードして上書きします。
呼び出し前の準備と使用手順¶
現在のワークスペースで 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 です。この 2 つの値のみ指定できます。アップロードするファイルの元の名前で用途が決まることはありません。 選択可能な値: ['logo.png', 'favicon.ico'] 例: logo.png取得または入力方法: Logo には 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取得または入力方法: ローカルで有効な Logo/ICO ファイルを準備し、パスを実際のファイルに置き換えます。 |
パラメータ補足説明¶
注意事項¶
- この API は form リクエストであり、ファイルの内容はフォーム内の file フィールドに格納されます。
- 1 回のリクエストで送信できるファイルは 1 つだけです。
- アップロードするファイルの元の名前に関係なく、保存時にはパラメータ 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 フィールドを使用し、有効なファイルを 1 つ選択してください。 |
| 500 | ft.InternalServerError | ディレクトリの作成、ファイルの保存、または後続のレスポンス処理に失敗 | 内部エラー | ファイルが書き込まれたか、権限/ディスクを確認し、traceId を保持してください。上書き前に旧バージョンを保持してください。失敗時でも一部のファイルが既に変更されている可能性があります。 |