画像関連リソースの取得¶
POST /api/v1/workspace/{workspace_uuid}/get_logo_url
概要¶
指定したワークスペース、ファイル名、言語に対応するロゴまたはサイトアイコンの 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 です。 |
クエリパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 が許可範囲外 | メッセージには、列挙型の検証に失敗したフィールドが示されます。 | パラメータ表に記載されているファイル名と言語を使用してください。 |