使う

画像とDropbox連携

業務行のasset_ref欄に、管理された原本、または外部の原本への参照を関連付けます。画像を表示するアプリは、この共通のメディアAPIを使います。

業務表（v2）の行の画像欄には、/v2/mediaを使います。/v1/assetsは、親の資源をnamespaceとresourceTypeで指定する、資産の経路です（APIリファレンスの「資産」）。

画像の機能と管理サイトのDropbox連携は環境による。アプリ向けフォルダー選択APIは準備中、共有URLの解決は未提供です。

管理原本と外部参照

保存方式	用途	解除した場合
managed_original	アプリが送った原本を、基盤が保持	メディアの状態・保持方針に従う
external_reference	Dropbox等の原本を複製せず、業務行へ関連付ける	関連の解除。外部原本は削除しない

外部原本の配置・整理・バックアップは原本の管理者が担当します。サムネイルや一時取得ファイルは、原本のバックアップにはなりません。

参照を登録して表示する

asset_ref欄を持つ表定義と業務行を用意します。
次のpolicyを取得し、現在の許可、媒体、上限、reference_stores、必要な版を確認します。
新しい画像には、assetIdとして、新しいUUIDを、呼び出し側で作ります。policyが返すstoreと、その中の相対パスを使い、参照を登録します。
添付一覧・metadataを取得し、認可された経路からthumbnailまたはcontentを表示します。

httpGET /v2/media/{collection}/{rowId}/{field}/policy
GET /v2/media/{collection}/{rowId}/{field}
POST /v2/media/{collection}/{rowId}/{field}/{assetId}/reference
GET /v2/media/{collection}/{rowId}/{field}/{assetId}/thumbnail
GET /v2/media/{collection}/{rowId}/{field}/{assetId}/content

完全なヘッダー・リクエスト・応答例も参照してください。以下は参照登録の本文だけの例です。storeはpolicyにある値を使い、相対パスは対象ストア内に限定します。次のヘッダーを付けます。If-Matchは、新しい画像では"0"、既存の画像の更新では、取得した画像の現在の版です。X-Parent-VersionとX-Schema-Versionは、policyや行の取得で得た、現在の値です。適当な値を作らないでください。Idempotency-Keyは、操作ごとに、新しく作ります。

json{
  "store": "sample-files",
  "relative_path": "examples/sample-image.png",
  "media_type": "image/png",
  "name": "サンプル画像"
}

APIには、Dropboxの共有URLやOSの絶対パスではなく、policyのstoreと、その中の相対パスを渡します。ブラウザー表示では、顧客アプリのサーバー側が、画像のバイナリーを取得して、ブラウザーに渡します。AuthorizationをURLへ付けないでください。

参照を登録すると、画像の関連付けと、画像の版が更新されます。親の行のasset_refの値や、親の行の版は、自動では更新されません。親の行に、assetIdを書き込む操作は不要で、任意のIDやURLの書き込みは、受理されません。画像の表示には、画像の一覧と取得のAPIを使います。関連の解除は、Dropbox上の原本の削除ではありません。

storeと、Dropboxの対応

storeは、利用環境で設定された保存先です。policyが、その利用環境で使える名前を返します。アプリが任意のパスや共有URLを指定して、Dropboxの接続を作る仕組みではありません。

管理サイトのDropbox連携では、同じDropboxアカウント・同じ権限範囲の通常利用なら、外部サービスへの同意一回で最大3フォルダーを設定します。認可が失効した場合などは、再同意が必要です。読取の許可は、フォルダーごとに、人と自律サービスへ個別に設定します。接続やフォルダー設定だけでは、読取の許可は付きません。

接続全体を解除すると、対象の全フォルダーの参照を遮断し、マウントを停止し、外部サービス側の認可を取り消します。保存した資格の削除と旧許可の無効化まで確認して、解除完了とします。途中で結果が不明なら、復旧待ちとして表示し、完了扱いにしません。外部原本は削除しません。再接続しても、以前のフォルダー設定や読取の許可は自動では戻りません。

管理サイトの操作と、アプリ向け公開APIは区別します。アプリからフォルダーを選ぶAPIは準備中、共有URLの解決は未提供です。外部原本の保管とバックアップの範囲は、保存先の運用条件で確認します。

原本の変更・移動・切断

登録時の原本と現在の内容を検査します。変更・移動を勝手に別の原本として採用せず、差分確認と版付きの再関連を行います。外部の原本に到達できないときは、エラーが返ります。サムネイルは登録したときに作ったものです。サムネイルが表示できても、今の原本に届くとは限りません。空の一覧を、正常な結果として扱わないでください。

業務行の添付一覧は取得できますが、アプリからDropboxフォルダーを選ぶ公開APIは準備中、共有URLの解決は未提供です。アプリは接続・未接続・原本変更を区別して表示します。

媒体と上限

PNG・JPEG・WebPは実形式をデコードして検証します。最大16M画素、サムネイルは320px以内のPNGです。
1ファイル最大32MiB、同時に処理するのは全体で2リクエスト・1人あたり1リクエストまで（待つのは8秒まで）、1行1欄に最大100資産です。解除済みIDも上限に含まれます。
SVGは対象外です。PDFはダウンロードのみ。Range、再開upload、動画変換、マルウェア検疫は未提供です。

実際に利用できる媒体・容量はpolicyを優先してください。認証切れ、権限不足、版競合、媒体不適合、依存停止の扱いはエラーと再試行にまとめています。