DAM アセットを移動するか、名前を変更する
保存されているオブジェクトを変更せずに、DAM アセットを移動するか、名前を変更します。
https://api2.transloadit.com/ dam/ assets/ {assetId}このエンドポイントはアルファ版です。URL、パラメーター、レスポンス、動作が大幅に変更され、既存の連携が動作しなくなる可能性があります。
このエンドポイントを呼び出す前に、リクエストに使用する Auth Key と同じ Workspace にある既存アセットの ID を取得してください。
/transloadit/store で保存したファイルについては、Assembly Status を取得し、ASSEMBLY_COMPLETED になるまで待ってください。返された results[stepName] 配列から、保存された各ファイルの workspace、asset_id、version_id、および返された path を控えておいてください。通常のファイルの id は、そのストレージアセット ID ではありません。以下の例では、ASSET_ID または params.asset_ids に asset_id を使用してください。
ネイティブな移動や名前変更を通じてアセットを追跡するには、asset_id を使用してください。上書き後も保持されている同じバイト列を選択するには、インポート時に version_id も追加してください。保存したパスは変更可能な場所であり、不変の参照ではありません。アクセスとバージョン保持のルールは引き続き適用されます。
移動先がルート以外の場合、同じ Workspace にある既存の移動先フォルダーの ID をあらかじめ把握している必要があります。以前に保存した移動または名前変更のレスポンスから、この ID を取得できます。単一アセットのレスポンスでは folder_id、一括移動のレスポンスでは assets[].folder_id です。これらのレスポンスは、その操作後のフォルダーを記述するものであり、フォルダーを検出するための API ではありません。
フォルダー ID ではなくパスがわかっている場合は、ストレージのファイルまたはフォルダーを移動するを使用してください。移動先の親フォルダーは、すでに存在している必要があります。この ID ベースのエンドポイントでアセットをルートに移動するには、destination_folder_id: null を使用してください。
params 内に filename または destination_folder_id の少なくとも一方を含めてください。ファイル名は、フォルダーパスを含まない名前である必要があります。
アセットを現在のフォルダー内で名前変更するには、以下のリクエスト例のように、params 内に filename だけを指定して送信してください。
代わりにアセットをルートに移動するには、destination_folder_id: null を明示的に含めてください。
{ "destination_folder_id": null, "filename": "renamed.jpg" }
別のフォルダーに移動する場合は、null をそのフォルダーの ID に置き換えてください。省略と null は異なる操作です。
アセットパスの制限
完全な移動先パス(フォルダーとファイル名)は、正規化後に 512 Unicode コードポイント以内、かつ 1024 UTF-8 バイト以内に収まる必要があります。ファイル名だけでは制限内に収まっていても、入れ子になったフォルダー内ではこれらの制限を超えることがあります。
リクエスト例
ASSET_ID に、リソースの値をパーセントエンコードせずに設定してください。
TRANSLOADIT_TOKEN に適切な Bearer トークンを設定し、curl を使用できるサーバー側のシェルでこのリクエストを実行してください。トークンが必要な場合は、以下のセットアップを展開してください。
Bearer トークンが必要ですか?
curl と jq を使用できる信頼できるサーバー側のシェルで、TRANSLOADIT_KEY と TRANSLOADIT_SECRET にそれぞれ Auth Key と Auth Secret を設定してください。両方の認証情報と、生成されるトークンは秘密にしてください。このセットアップをブラウザーのコードで実行しないでください。
まず、このエンドポイントに必要なスコープを持つトークンを作成してください。Auth Key は、それらのスコープをすでに許可している必要があります。
if ! TOKEN_RESPONSE="$(curl --fail-with-body -sS \
--request POST \
--url 'https://api2.transloadit.com/token' \
--user "${TRANSLOADIT_KEY:?Set TRANSLOADIT_KEY}:${TRANSLOADIT_SECRET:?Set TRANSLOADIT_SECRET}" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'aud=api2' \
--data-urlencode 'scope=dam:write')"; then
printf '%s\n' "$TOKEN_RESPONSE" >&2
exit 1
fi
TRANSLOADIT_TOKEN="$(printf '%s' "$TOKEN_RESPONSE" |
jq -er '.access_token | strings | select(length > 0)')" || exit 1
このシェルを開いたままにし、以下のリクエストを実行してください。トークンが有効な間は再利用してください。
curl --fail-with-body -sS --request PATCH \
--url "https://api2.transloadit.com/dam/assets/${ASSET_ID:?Set ASSET_ID}" \
--header "Authorization: Bearer ${TRANSLOADIT_TOKEN:?Set TRANSLOADIT_TOKEN}" \
--data-urlencode 'params={"filename":"renamed.jpg"}'
認証
このエンドポイントは、署名付きの params または Bearer トークンを受け付けます。設定手順については、認証を参照してください。
Auth Key または Bearer トークンに必要なスコープ: dam:write。
Signature 付きリクエストには、signature と、将来の時刻を示す params.auth.expires タイムスタンプの両方が必要です。Bearer トークンには、どちらも必要ありません。
パスパラメーター
assetId(パスセグメント)、必須。パターン:^[A-Za-z0-9_-]{21}[AQgw]$, 最小長: 22, 最大長: 22
フォームフィールド
コンテンツタイプ: application/x-www-form-urlencoded
params(JSON 文字列)、必須。JSON エンコードされたオブジェクトで、サポートされるキーは以下のとおりです。signature(文字列)。署名付きリクエストでは必須です。Bearer トークンを使用する場合は、このフィールドを省略してください。
params フィールド内でサポートされるキー
この一覧の認証フィールドは、署名付きリクエストに適用されます。Bearer トークンを使用する場合は、params.auth と、それとは別の signature フィールドを省略できます。以下の認証方式ごとのリクエストパラメーターを比較してください。
完全な JSON スキーマ
params: このオブジェクトでは、一覧に記載されているフィールドのみが受け付けられます。
| フィールド | 型と説明 |
|---|---|
params.署名付きリクエストでは必須。Bearer トークンを使用する場合は任意 | DAM の変更操作に使用する Transloadit API キーと Signature Authentication のメタデータを含みます。
|
params.必須 | string将来の日時を示す ISO 8601 形式の有効期限タイムスタンプ。リクエストが署名されている場合、または Signature Authentication が必要な場合は必須です。Bearer 認証を使用するリクエストでは省略できます。 |
params.必須 | stringリクエストの認証に使用する Transloadit API キー |
params. | "DELETE" | "GET" | "PATCH" | "POST"これらの署名済み params が認可するリクエストの HTTP メソッド。大文字で指定します。すべての署名付きリクエストで、 |
params. | string (最大長: 2048)これらの署名付き params が認可するリクエストの URL パス(例: 検証パターン(正規表現)^\/[^?#]*$ |
params. | string | null移動先フォルダーの ID。アセットをルートに移動するには 次のいずれかのスキーマが適用される場合があります: stringstring大文字と小文字を区別する、正規形式の 22 文字の Base64URL DAM 識別子。 検証パターン(正規表現)^[A-Za-z0-9_-]{21}[AQgw]$null |
params. | string (最小長: 1, 最大長: 255)フォルダーパスを含まない新しいファイル名。名前は Unicode NFC に正規化され、大文字と小文字は引き続き区別されます。空白文字のみの名前、 |
params. | string | integer各 Signature を一意にし、Signature の意図しない再利用を防ぐために、署名付きリクエストのパラメーターに含める一意のランダムな値。 |
認証方式別のリクエストパラメーター
署名付き params
Auth Key を params.auth.key として含めてください。リクエストに署名する場合は、将来の時刻を示す params.auth.expires タイムスタンプを含め、Signature を別の signature フィールドで送信してください。以下のフィールド定義では、params 内のパスを使用しています。
完全な JSON スキーマ
params: このオブジェクトでは、一覧に記載されているフィールドのみが受け付けられます。
上記のフィールド定義を使用します: params.auth, params.destination_folder_id, params.filename, params.nonce
Bearer トークンを使用する場合
Bearer トークンを Authorization ヘッダーで送信してください。params.auth と、それとは別の signature フィールドは省略できます。他の必須パラメーターの要件は引き続き適用されます。以下のフィールド定義では、params 内のパスを使用します。
完全な JSON スキーマ
params: このオブジェクトでは、一覧に記載されているフィールドのみが受け付けられます。
上記のフィールド定義を使用します: params.destination_folder_id, params.filename, params.nonce
| フィールド | 型と説明 |
|---|---|
params. | DAM の変更操作に使用する Transloadit API キーと Signature Authentication のメタデータを含みます。
|
params. | string将来の日時を示す ISO 8601 形式の有効期限タイムスタンプ。リクエストが署名されている場合、または Signature Authentication が必要な場合は必須です。Bearer 認証を使用するリクエストでは省略できます。 |
params. | stringリクエストの認証に使用する Transloadit API キー |
params. | "DELETE" | "GET" | "PATCH" | "POST"これらの署名済み params が認可するリクエストの HTTP メソッド。大文字で指定します。すべての署名付きリクエストで、 |
params. | string (最大長: 2048)これらの署名付き params が認可するリクエストの URL パス(例: 検証パターン(正規表現)^\/[^?#]*$ |
レスポンス
レスポンスボディの例を以下に示します:
{
"asset": {
"asset_id": "AAAAAAAAAAAAAAAAAAAAAA",
"height": 600,
"mime": "image/jpeg",
"path": "renamed.jpg",
"size": 12345,
"version_id": "AAAAAAAAAAAAAAAAAAAAAQ",
"width": 800,
"workspace": "example-workspace"
},
"asset_id": "AAAAAAAAAAAAAAAAAAAAAA",
"deleted_at": null,
"filename": "renamed.jpg",
"folder_id": null,
"message": "The DAM asset was successfully moved.",
"ok": "DAM_ASSET_MOVED",
"path": "renamed.jpg",
"updated_at": "2026-09-12T10:00:00.000Z"
}2xx 成功
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
レスポンスには、このオブジェクトについて記載されているフィールドのみが含まれます。
| フィールド | 型と説明 |
|---|---|
asset必須 |
|
asset.必須 | string安定したアセット ID です。ネイティブの移動や名前変更を行っても維持されます。現在のバイト列を選択するには、バージョンを指定せずにこの ID を使用してください。 検証パターン(正規表現)^[A-Za-z0-9_-]{21}[AQgw]$ |
asset. | booleanすべてのピクセルが不透明であっても、画像にアルファチャンネルがあるかどうかを示します。ThumbHash の抽出に成功した場合に含まれ、省略されている場合は不明であることを意味します。 |
asset. | integer (最小値(境界値を含まない): 0, 最大値: 9007199254740991)EXIF の向きを適用した後の表示の高さ(ピクセル単位、判明している場合)。 |
asset. | string保存されたバイト列の MD5 チェックサム(小文字表記、利用可能な場合)。 検証パターン(正規表現)^[a-f0-9]{32}$ |
asset.必須 | null | string保存されているバイト列の MIME タイプ。不明な場合は null。 |
asset.必須 | string (最小長: 1)Workspace を基準とした、変更可能な現在の場所です。名前を変更すると、以前のパスは最新の場所を示さなくなります。上書きによって、このパスにあるデータのバイト列が変わることがあります。 |
asset. | string保存されたバイト列の SHA-256 チェックサム(小文字表記、利用可能な場合)。 検証パターン(正規表現)^[a-f0-9]{64}$ |
asset.必須 | integer (最小値: 0, 最大値: 9007199254740991)保存されているファイルのサイズ(バイト単位)。 |
asset. | stringこのバージョンの表示ピクセルを表す、Base64 エンコードされた ThumbHash。このバージョンを生成した Step で output_meta.thumbhash を指定して要求した場合に提供されます。これは画像データです。オリジナルと同じアクセス制御を適用してください。 検証パターン(正規表現)^(?:[A-Za-z0-9+/]{4}){1,15}(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)$ |
asset.必須 | stringこのアセットの特定の変更不可能なバージョンです。asset_id と組み合わせて、保持されているバイト列を選択します。バージョンが存在しない場合、現在のバージョンにフォールバックすることは決してありません。 検証パターン(正規表現)^[A-Za-z0-9_-]{21}[AQgw]$ |
asset. | integer (最小値(境界値を含まない): 0, 最大値: 9007199254740991)EXIF の向きを適用した後の表示幅(ピクセル単位、判明している場合)。 |
asset.必須 | string (最小長: 1)このアセットを所有する Workspace のスラッグ。このアセットを読み取る、または管理する際は、同じ Workspace に対して認証してください。 |
asset_id必須 | string大文字と小文字を区別する、正規形式の 22 文字の Base64URL DAM 識別子。 検証パターン(正規表現)^[A-Za-z0-9_-]{21}[AQgw]$ |
deleted_at必須 | string | null検証パターン(正規表現)^(([0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-((0[13578]|1[02])-(0[1-9]|[12][0-9]|3[01])|(0[469]|11)-(0[1-9]|[12][0-9]|30)|(02)-(0[1-9]|1[0-9]|2[0-8])))T([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9](\.[0-9]+)?)?(Z)$ |
filename必須 | string (最小長: 1) |
folder_id必須 | string | null大文字と小文字を区別する、正規形式の 22 文字の Base64URL DAM 識別子。 検証パターン(正規表現)^[A-Za-z0-9_-]{21}[AQgw]$ |
message必須 | string (最小長: 1) |
ok必須 | string (常に: "DAM_ASSET_MOVED") |
path必須 | string (最小長: 1) |
updated_at必須 | string検証パターン(正規表現)^(([0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-((0[13578]|1[02])-(0[1-9]|[12][0-9]|3[01])|(0[469]|11)-(0[1-9]|[12][0-9]|30)|(02)-(0[1-9]|1[0-9]|2[0-8])))T([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9](\.[0-9]+)?)?(Z)$ |
エラーレスポンス
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
レスポンスには追加のフィールドが含まれる場合があります。
| フィールド | 型と説明 |
|---|---|
assembly_id | string |
error | string (最小長: 1) |
http_code | number | string
|
message | string人が読んで理解できる形式のエラー説明です。文言は変わる場合があるため、特定の失敗を処理する際は |
reason | null | string | number | boolean | Array<任意の値> | object次のいずれかのスキーマが適用される場合があります: nullstringnumberbooleanArray<任意の値>Array<任意の値>配列要素のスキーマ任意の値objectobject追加プロパティのスキーマ任意の値 |
HTTP 400
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
名前付きエラーと一般的なエラー形式
error: "DAM_INVALID_REQUEST"
ストレージリクエストのパラメーターが無効です。
レスポンスには追加のフィールドが含まれる場合があります。
一般的なエラー形式
HTTP 404
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
名前付きエラーと一般的なエラー形式
error: "DAM_RESOURCE_NOT_FOUND"
要求された DAM リソースが見つかりませんでした。
レスポンスには追加のフィールドが含まれる場合があります。
一般的なエラー形式
HTTP 409
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
名前付きエラーと一般的なエラー形式
error: "DAM_MUTATION_CONFLICT"
DAM の変更操作が既存のリソースと競合しています。
レスポンスには追加のフィールドが含まれる場合があります。
一般的なエラー形式
HTTP 500
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
名前付きエラーと一般的なエラー形式
error: "DAM_MUTATION_FAILED"
DAM の変更操作を完了できませんでした。もう一度お試しください。
レスポンスには追加のフィールドが含まれる場合があります。