CAPの@cap-js/attachmentsプラグインを使ってみる

## はじめに
CAPの@cap-js/attachmentsプラグインは今年の3月にリリースされた機能で、簡単な設定だけでFiori elementsアプリに添付ファイルをアップロードするセクションを追加することができます。現在はまだベータのステータスです。

https://cap.cloud.sap/docs/releases/mar24#new-attachments-plugin

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/4e21a17b-7556-29d8-f51a-c42c433b5f84.png)

設定方法は以下のリポジトリに書かれています。設定している中でつまづいた点があったので、それを含めてこの記事で説明します。

https://github.com/cap-js/attachments

## ステップ
1. プロジェクトを作成
1. @cap-js/attachmentsをインストール
1. Attachmentsを追加
1. Fiori elementsアプリを作成
1. デプロイ

### 1. プロジェクトを作成
以下のコマンドでプロジェクトを作成し、サンプルのデータモデルも追加します。

```
cds init
cds add tiny-sample
```
追加されたデータモデルは以下です。

```:db/data-model.cds
namespace my.bookshop;

entity Books {
  key ID : Integer;
  title  : String;
  stock  : Integer;
}
```

### 2. @cap-js/attachmentsをインストール
@cap-js/attachmentsをインストールします。

```
 npm add @cap-js/attachments
 ```

### 3. Attachmentsを追加
db/attachments.cdsファイルを追加します。元のdata-model.cdsに設定を追加してもよいのですが、「関心の分離」のベストプラクティスに従って別ファイルにするのがよいとのことです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/a4971b64-6537-c817-bdde-b419406a1f56.png)

"Books"エンティティにAttachmentsのアスペクトをコンポジションとして追加しています。

```
using { my.bookshop as my } from './data-model';
using { Attachments } from '@cap-js/attachments';

extend my.Books with { attachments: Composition of many Attachments }
```
Attachmentを使うための設定はこれだけです。
`cds watch`でサービスを実行してメタデータを見てみると、"Books_attachmehts"というエンティティが追加されています。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/d88515fd-b491-48f7-8acf-af9e58adaf3b.png)
`

### 4. Fiori elementsアプリを作成
Fiori toolsを使ってFiori elements (List Report)アプリを作成します。

データソースには"Use a Local CAP Project"を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/ca2827ae-43b3-b6b0-ac96-ca5b3dc3ff79.png)
メインのエンティティと、ナビゲーションプロパティとして"attachments"を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/975a766e-2460-4fcd-5296-b2b03881c311.png)
プロジェクトの設定を以下のように行います。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/97d95b9e-614c-5786-b1db-8b023d40ce3a.png)

この状態でFiori elementsアプリを実行し、Object Pageに遷移すると画面が固まってしまいました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/22f7ddcf-d2e0-6d60-9f7a-3febe7027a9e.png)

@cap-js/attachmentsの[リポジトリ](https://github.com/cap-js/attachments)で説明に使われていたプロジェクトは、SAPUI5バージョンが1.121.0だったので、index.htmlでバージョンを1.121.0にすると動くようになりました（1.122.0でも動いたので、以下では1.122.0にしています）。1.123.0以降のバージョンでは今のところ動かないようでした。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/1b232831-2a72-d8ee-8f85-71470568d760.png)

※デプロイ前にはmanifest.jsonの`minUI5Version`も変更しておきましょう
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/6c0fe009-8c6e-7a8d-46ef-b37963a07b91.png)

Object Pageを開くと、"Attachments"のテーブルが表示されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/f99f82ef-901f-30e7-b72e-6f5876dded6c.png)

編集モードにすると"Upload"ボタンからファイルをアップロードすることができます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/c7f0b646-5e62-9073-021d-b755058fd380.png)

以下がアップロードした結果です。
※"Status"という項目はウイルススキャンのステータスを格納するための項目のようですが、ドキュメントに説明がなく、どうやってスキャンを有効にするのかは不明です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/105370e9-0841-3e59-e643-42ad0d8dbee0.png)

裏では以下のアノテーションが生成されており、そのおかげで添付ファイルのセクションがUIに表示されるようになっているのでした。

- Books_attachmentsのためのUI.LineItemアノテーション
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/2a235946-92a8-80e1-14e1-5a24bd2f99f5.png)

- LineItemをObject Pageに追加するためのUI.ReferenceFacetアノテーション
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/4f2a0191-7c9c-f4f2-14b2-c92c341e63d9.png)

::: note warn
@cap-js/attachmentsプラグインを使わずに添付ファイル用のエンティティとアノテーションを定義した場合、以下の見え方になりました。使われているコントロールやボタン名、テーブルツールバーのボタンも違っています。この方法では、アップロードもエラーになってしまいました。@cap-js/attachmentsは他にも何か裏でやっていそうです。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/b582d4db-b893-9482-b7d5-e2cb3310ee59.png)

:::

### 5. デプロイ
まずは普通に、以下の手順でデプロイしてみました。

```
cds add hana --for production
cds add xsuaa --for production
mbt build --mtar archive
cf deploy mta_archives/archive.mtar
```
::: note info
Fiori elementsアプリをHTML5 Application Repositoryにデプロイするためには、以下のブログに記載の設定も必要です。

[Deploying a CAP based Fiori app to a central Launchpad](https://community.sap.com/t5/technology-blogs-by-members/how-to-deploy-a-ui5-app-inside-a-cap-mta-project-and-make-it-available-from/ba-p/13560177)
:::

その結果、CAPのサービス起動時にエラーになりました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276021/efce2d73-e36f-882f-5a23-00fb5edc4bd3.png)

@cap-js/attachmentsはデフォルトではファイルの格納先としてSAP Object Storeを使うようになっており、そのためには以下の設定を行います。

https://github.com/cap-js/attachments?tab=readme-ov-file#using-sap-object-store

格納先としてSAP HANA Cloudを使いたい場合、package.jsonに以下の設定が必要です。

```json
    "cds": {
        "requires": {
            ...,
            "attachments": {
                "kind": "db"
            }             
        }
    }
```
上記の設定後、デプロイは成功しHTML5 Application Repositoryから実行できるようになりました。

## まとめ
- @cap-js/attachmentsを使う場合、UI5バージョンは1.122.0を使用する（2024年5月現在）
- ファイルの格納先としてSAP HANA Cloudを使用する場合、package.jsonに設定を追加する