- ガイド
- Assets API
Assets APIの概要
Table of contents
Assets APIとは
Newtにアップロードされた画像・動画・書類などのファイルの取得と操作を可能にするAPIです。CDN経由でデータを取得でき、Webサイト・アプリケーションのパフォーマンスを向上させることができます。
またクエリパラメータを利用して、簡単にファイルのフォーマット変更やリサイズを行えます。
詳細については リファレンス をご確認ください。
※ 2023/5/29以前に作成されたスペースでは、デフォルトでAssets APIがオフとなっています。有効化する場合は、こちら のドキュメントをご確認ください。
Asset APIのURLと画像・ファイルの取得
例えば画像フィールドを利用している場合、コンテンツのJSONデータは以下のようになります。
{
"image": {
"_id": "610b77253adec80018727d57",
"src": "https://xxxxx.assets.newt.so/v1/c3da2899-5345-4368-b23b-f7a2b81bc0ab/example.jpeg",
"fileType": "image/jpeg",
"fileName": "example.jpeg",
"fileSize": 2403201,
"width": 600,
"height": 400,
"title": "example",
"altText": "example image",
"description": "",
"metadata": {}
}
}この src に設定されている https://xxxxx.assets.newt.so/v1/c3da2899-5345-4368-b23b-f7a2b81bc0ab/example.jpeg のようなURLがAssets APIのURLとなります。
URLの構成要素は以下の通りです。
https://{spaceUid}.assets.newt.so/v1/{assetUid}/{assetName}
https://xxxxx.assets.newt.so/v1/c3da2899-5345-4368-b23b-f7a2b81bc0ab/example.jpegこのURLにアクセスすることで、画像を表示したり、ファイルをダウンロードすることができます。
CDNを利用した配信
Assets APIを利用すると、画像や動画などのファイルはグローバルに分散されたCDNを経由して配信されます。
クエリパラメータを利用して加工したファイルについてもキャッシュされるため、高速なレスポンスを返すことができます。
様々なクエリ
クエリパラメータを利用することで、以下のことを実現できます。
- 画像・動画のサイズ変更
- 画像の品質変更
- ファイルのフォーマット変更
- ダウンロード用のリンクの作成
それぞれの詳細については リファレンス をご確認ください。
変換可能なフォーマットは以下の通りです。
| 変換前 | 変換後 |
|---|---|
| JPEG | png, webp, avif, tiff |
| PNG | jpeg, webp, avif, tiff |
| WEBP | jpeg, png, avif, tiff |
| AVIF | jpeg, png, webp, tiff |
| TIFF | jpeg, png, webp, avif |
| SVG | jpeg, png, webp, avif, tiff |
| MP4 | webm |
| MOV | mp4, webm |
| WEBM | mp4 |
| AVI | mp4, webm |
| DOC | docx, pdf |
| DOCX | doc, pdf |
| XLS | xlsx, csv, pdf |
| XLSX | xls, csv, pdf |
| PPT | pptx, pdf |
| PPTX | ppt, pdf |
これらのクエリを利用することで、Newtには1つだけファイルをアップロードしておき、そこからページごとに最適なサイズやフォーマットに変換してデータを取得できます。
例えば以下のようなことを実現できます。
ページごとに最適なサイズ・品質で取得する
オリジナルで利用する場合、サムネイルで利用する場合、アイコンで利用する場合など、表示サイズに応じて、取得するサイズや品質を設定できます。
// サムネイルで利用する場合
?width=600
// アイコンで利用する場合
?width=100&quality=50ブラウザごとに最適なフォーマットで取得する
pictureタグを利用して、ブラウザが webp 形式に対応していればwebpの画像を表示し、対応していない場合は jpeg や png などで表示できます。
// webp形式に変換
?format=webp
// jpeg形式に変換
?format=jpegダウンロードリンクを複数用意する
ユーザーが選択できるように、複数の形式でダウンロードリンクを用意できます。
// xlsx形式に変換
?format=xlsx&download=example.xlsx
// pdf形式に変換
?format=pdf&download=example.pdf制限
Assets APIの利用には以下の制限があります。ご注意ください。
- 外部ストレージを有効にしている場合は、適用されません
- 20MB以上のファイルの場合は、適用されません
- 画像・動画以外のファイルで、フォーマット変更を行えるのは有料プランのスペースのみとなります
- 2023/5/29以前に作成したスペースで有効化する場合は、こちら のドキュメントをご確認ください。
詳細については リファレンス をご確認ください。
