# 画像とDropbox連携

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

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

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

## 管理原本と外部参照

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

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

## 参照を登録して表示する

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

```http
GET /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
```

[完全なヘッダー・リクエスト・応答例](examples.md)も参照してください。以下は参照登録の本文だけの例です。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を優先してください。認証切れ、権限不足、版競合、媒体不適合、依存停止の扱いは[エラーと再試行](errors.md)にまとめています。