#HTTP API

添付ファイルフィールドとファイルコレクションのファイルアップロードは、どちらもHTTP APIで処理できます。添付ファイルやファイルコレクションが利用するストレージエンジンによって、呼び出し方法がそれぞれ異なります。

#サーバーサイドアップロード

S3、OSS、COSなど、プロジェクトに組み込まれているオープンソースのストレージエンジンの場合、HTTP APIはUIのアップロード機能と同じように呼び出され、ファイルはすべてサーバーサイドでアップロードされます。APIを呼び出す際には、ユーザーログインに基づくJWTトークンをAuthorizationリクエストヘッダーに含める必要があります。含めないとアクセスが拒否されますのでご注意ください。

#添付ファイルフィールド

添付ファイルコレクション（attachments）リソースに対してcreate操作を実行し、POSTリクエストを送信してfileフィールドからバイナリコンテンツをアップロードします。この呼び出し後、ファイルはデフォルトのストレージエンジンにアップロードされます。

curl -X POST \
    -H "Authorization: Bearer <JWT>" \
    -F "file=@<path/to/file>" \
    "http://localhost:3000/api/attachments:create"

異なるストレージエンジンにファイルをアップロードしたい場合は、attachmentFieldパラメーターを使って、所属するコレクションフィールドに設定されているストレージエンジンを指定できます（設定されていない場合は、デフォルトのストレージエンジンにアップロードされます）。

curl -X POST \
    -H "Authorization: Bearer <JWT>" \
    -F "file=@<path/to/file>" \
    "http://localhost:3000/api/attachments:create?attachmentField=<collection_name>.<field_name>"

#ファイルコレクション

ファイルコレクションにアップロードすると、自動的にファイルレコードが生成されます。ファイルコレクションリソースに対してcreate操作を実行し、POSTリクエストを送信してfileフィールドからバイナリコンテンツをアップロードしてください。

curl -X POST \
    -H "Authorization: Bearer <JWT>" \
    -F "file=@<path/to/file>" \
    "http://localhost:3000/api/<file_collection_name>:create"

ファイルコレクションへのアップロードでは、ストレージエンジンを指定する必要はありません。ファイルは、そのコレクションに設定されているストレージエンジンにアップロードされます。

#クライアントサイドアップロード

商用プラグイン S3-Pro を通じて提供されるS3互換のストレージエンジンの場合、HTTP APIでのアップロードはいくつかのステップに分けて呼び出す必要があります。

#添付ファイルフィールド

1. ストレージエンジン情報の取得

   ストレージコレクション（storages）に対してgetBasicInfo操作を実行し、ストレージ名（storage name）を含めてストレージエンジンの設定情報をリクエストします。

   curl 'http://localhost:13000/api/storages:getBasicInfo/<storage_name>' \
     -H 'Authorization: Bearer <JWT>'

   返されるストレージエンジン設定情報の例：

   {
     "id": 2,
     "title": "xxx",
     "name": "xxx",
     "type": "s3-compatible",
     "rules": { ... }
   }

2. サービスプロバイダーからプリサイン情報（Presigned URL）を取得

   fileStorageS3リソースに対してcreatePresignedUrl操作を実行し、POSTリクエストを送信してbodyにファイル関連情報を含め、プリサインアップロード情報を取得します。

   curl 'http://localhost:13000/api/fileStorageS3:createPresignedUrl' \
     -X POST \
     -H 'Accept: application/json, text/plain, */*' \
     -H 'Authorization: Bearer <JWT>' \
     -H 'Content-Type: application/json' \
     --data-raw '{"name":<name>,"size":<size>,"type":<type>,"storageId":<storageId>,"storageType":<storageType>}'

   注：

   • name: ファイル名
   • size: ファイルサイズ（バイト単位）
   • type: ファイルのMIMEタイプです。参考：一般的なMIMEタイプ
   • storageId: ストレージエンジンのID（ステップ1で返されるidフィールド）
   • storageType: ストレージエンジンのタイプ（ステップ1で返されるtypeフィールド）

   リクエストデータの例：

   --data-raw '{"name":"a.png","size":4405,"type":"image/png","storageId":2,"storageType":"s3-compatible"}'

   取得したプリサイン情報のデータ構造は以下の通りです。

   {
     "putUrl": "https://xxxxxxx",
     "fileInfo": {
       "key": "xxx",
       "title": "xxx",
       "filename": "xxx",
       "extname": ".png",
       "size": 4405,
       "mimetype": "image/png",
       "meta": {},
       "url": ""
     }
   }

3. ファイルのアップロード

   返されたputUrlを使ってPUTリクエストを実行し、ファイルをbodyとしてアップロードします。

   curl '<putUrl>' \
     -X 'PUT' \
     -T <file_path>

   注：

   • putUrl: 前のステップで返されたputUrlフィールド
   • file_path: アップロードするローカルファイルのパス

   リクエストデータの例：

   curl 'https://xxxxxxx' \
    -X 'PUT' \
    -T /Users/Downloads/a.png

4. ファイルレコードの作成

   アップロードが成功したら、添付ファイルコレクション（attachments）リソースに対してcreate操作を実行し、POSTリクエストを送信してファイルレコードを作成します。

   curl 'http://localhost:13000/api/attachments:create?attachmentField=<collection_name>.<field_name>' \
     -X POST \
     -H 'Accept: application/json, text/plain, */*' \
     -H 'Authorization: Bearer <JWT>' \
     -H 'Content-Type: application/json' \
     --data-raw '{"title":<title>,"filename":<filename>,"extname":<extname>,"path":"","size":<size>,"url":"","mimetype":<mimetype>,"meta":<meta>,"storageId":<storageId>}'

   data-rawの依存データについて：

   • title: 前のステップで返されたfileInfo.titleフィールド
   • filename: 前のステップで返されたfileInfo.keyフィールド
   • extname: 前のステップで返されたfileInfo.extnameフィールド
   • path: デフォルトは空
   • size: 前のステップで返されたfileInfo.sizeフィールド
   • url: デフォルトは空
   • mimetype: 前のステップで返されたfileInfo.mimetypeフィールド
   • meta: 前のステップで返されたfileInfo.metaフィールド
   • storageId: ステップ1で返されたidフィールド

   リクエストデータの例：

     --data-raw '{"title":"ATT00001","filename":"ATT00001-8nuuxkuz4jn.png","extname":".png","path":"","size":4405,"url":"","mimetype":"image/png","meta":{},"storageId":2}'

#ファイルコレクション

最初の3つのステップは添付ファイルフィールドへのアップロードと同じです。ただし、4番目のステップでは、ファイルコレクションリソースに対してcreate操作を実行し、POSTリクエストを送信してbodyにファイル情報をアップロードすることで、ファイルレコードを作成する必要があります。

curl 'http://localhost:13000/api/<file_collection_name>:create' \
  -H 'Authorization: Bearer <JWT>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"title":<title>,"filename":<filename>,"extname":<extname>,"path":"","size":<size>,"url":"","mimetype":<mimetype>,"meta":<meta>,"storageId":<storageId>}'

data-rawの依存データについて：

• title: 前のステップで返されたfileInfo.titleフィールド
• filename: 前のステップで返されたfileInfo.keyフィールド
• extname: 前のステップで返されたfileInfo.extnameフィールド
• path: デフォルトは空
• size: 前のステップで返されたfileInfo.sizeフィールド
• url: デフォルトは空
• mimetype: 前のステップで返されたfileInfo.mimetypeフィールド
• meta: 前のステップで返されたfileInfo.metaフィールド
• storageId: ステップ1で返されたidフィールド

リクエストデータの例：

  --data-raw '{"title":"ATT00001","filename":"ATT00001-8nuuxkuz4jn.png","extname":".png","path":"","size":4405,"url":"","mimetype":"image/png","meta":{},"storageId":2}'