ご覧のページは、お客様の利便性のために一部機械翻訳されています。また、ドキュメントは頻繁に更新が加えられており、翻訳は未完成の部分が含まれることをご了承ください。最新情報は都度公開されておりますため、必ず英語版をご参照ください。翻訳に問題がある場合は、こちらまでご連絡ください。

クライアント拡張との連携

Liferayセルフホスト Liferay SaaS Liferay PaaS

Liferay DXP 7.4

クライアント拡張機能を使用すると、OSGi モジュールをデプロイせずに Liferay を拡張できます。従来のモジュール開発と同様に、クライアント拡張機能は Liferay Workspaceに存在します。学習から始めましょう

クライアント拡張機能の開発を開始するために必要なツール
構成ファイルでクライアント拡張機能を定義する方法
クライアント拡張機能を展開する方法

必要なツールと設定

クライアント拡張機能を開発するための 3 つの前提条件をインストールします。

サポートされている Javaのバージョン。

注

サポートされている JDK、データベース、環境に関する情報については、互換性マトリックスを確認してください。推奨される JVM 設定については、 JVM 構成を参照してください。
Liferay ワークスペース。サンプルクライアント拡張プロジェクトを含むワークスペースをダウンロードするには、以下を実行します。
```
curl -o com.liferay.sample.workspace-latest.zip https://repository.liferay.com/nexus/service/local/artifact/maven/content\?r\=liferay-public-releases\&g\=com.liferay.workspace\&a\=com.liferay.sample.workspace\&\v\=LATEST\&p\=zip
```
クライアント拡張プロジェクト ( client-extensions/ ディレクトリ内) を独自のワークスペースにコピーするか、サンプルワークスペースを直接使用することができます。
Liferay SaaS を使用している場合は、 lcp CLI ツールが必要です。

クライアント拡張機能の開発は、 ワークスペースプラスプロジェクト モデルに従います。 Liferayワークスペース内で、 [workspace-root]/client-extensionsの下にクライアント拡張プロジェクトを実装します。プロジェクトの client-extension.yaml ファイルはクライアント拡張機能を定義し、ビルドプロセスによって各プロジェクトに対して 1 セットの出力が生成されます。構築されたクライアント拡張プロジェクトは、Liferay Universal File Format Archive (LUFFA) と呼ばれるデプロイ可能な *.zip アーカイブです。

プロジェクト内のクライアント拡張機能のグループ化

単一のプロジェクトにグループ化されたクライアント拡張機能は、ビルド時に単一の展開可能なユニットを構成します。クライアント拡張機能を適切な場所にグループ化できます (たとえば、関連するタスクで作業する場合の効率を向上させるため) が、制限があります。

単一プロジェクト内のすべてのクライアント拡張機能は、そのプロジェクトに固有のワークロードを表す Docker コンテナーに関連付けられているため、グループ化に対応しているのは特定の種類のクライアント拡張機能のみです。たとえば、マイクロサービスはLiferayの外部で実行されるワークロードを表すため、マイクロサービスクライアント拡張機能は構成クライアント拡張機能とのみグループ化できます。

クライアント拡張機能は次の方法でグループ化できます。

同じタイプのクライアント拡張（例：複数のバッチクライアント拡張）
バッチクライアント拡張機能を使用した構成クライアント拡張機能
フロントエンドクライアント拡張機能を使用したクライアント拡張機能の構成
マイクロサービスクライアント拡張機能を使用した構成クライアント拡張機能

互換性のないクライアント拡張機能のグループ化 (例: フロントエンドとマイクロサービス) を含むプロジェクトのビルドは、エラーで失敗します。

クライアント拡張機能の構成

クライアント拡張機能は、次のプロパティを持つ client-extension.yaml ファイルで定義されます。

名前: Liferay UI に表示される名前を入力します。 UI で構成できない場合は、 名前 値は使用されません。

type: クライアント拡張機能のタイプを設定します (例: themeCSS)。タイプによって、Liferay がクライアント拡張機能をデプロイ時に処理する方法が決まります。

dxp.lxc.liferay.com.virtualInstanceId: デプロイ先の仮想インスタンスIDを入力します。このプロパティは Liferay PaaS と互換性がありません。

各クライアント拡張プロジェクトには、ワークスペースの client-extensions/ フォルダー内に独自のフォルダーがあります。クライアント拡張プロジェクトには、1 つ以上のクライアント拡張を定義する単一の client-extension.yaml ファイルが含まれています。たとえば、 iframe-2 プロジェクトの client-extension.yaml は、3 つの iframe クライアント拡張機能を定義します: Baseball、 Football、 Hockey。

使用しているクライアント拡張機能の種類 (およびそれを実行する環境の種類) に応じて、他のファイルを使用してクライアント拡張機能の構造またはコンテナーを構成することもできます。たとえば、 Dockerfile を使用して、カスタムマイクロサービスのコンテナーを構成します。詳細については、クライアント拡張機能のパッケージ化を参照してください。

クライアント拡張機能の組み立て

クライアント拡張機能をビルドすると、ファイルが自動的に作成され、結果の LUFFAにパッケージ化されます。ビルドまたはプロジェクトファイルから含めるファイルを構成するには、 client-extension.yaml ファイルで assemble ブロックを定義します。

assembleClientExtension Gradle タスクは、クライアント拡張プロジェクト内で gradle build または gradle deploy を実行すると実行されます。実行中、プロジェクトの assemble ブロックで指定されたファイルは、プロジェクト内の build/liferay-client-extension-build/ フォルダに配置されます。このフォルダ内のすべては、LUFFA の作成に使用されます (例: dist/my-client-extension-project.zip)。

注

クライアント拡張プロジェクトに、 package.json ファイルが含まれており、 build スクリプトが定義されている場合、プロジェクトをビルドすると、スクリプトが自動的に実行されます。ビルドのこの部分は、ファイルがコピーされる前に実行されるため、 assemble ブロックでタスクの出力場所を指定できます。

assemble ブロックは、インクルードするファイルに関する複数の指示を含めることができる YAML 配列です。各命令セットは次のパターンに従います。

- from: [some folder in your project]
  include: [single file or glob match]
  into: [output location in archive]

アセンブル 配列には次のプロパティがあります。

from: クライアント拡張機能アーカイブにファイルをコピーするフォルダーを指定します。
include: from ディレクトリから含める単一のファイルまたはファイルのサブセットに一致する glob を指定します。定義されていない場合は、すべてのファイルが再帰的にインクルードされます ( **/*と同等)。

必要に応じて、複数の include パターンの配列を使用できます。
```
assemble:
    - from: build
      include:
        - "vite/js/*.js"
        - "vite/css/*.css"
      into: static
```
をにコピー: 結果の LUFFA 内のどこに一致するリソースをコピーするかを指定します。

フロントエンドクライアント拡張機能の静的リソースは、 static/ ディレクトリにコピーする必要があります。 Liferay はこれらを、セルフホストインスタンス内の静的リソースとして、または Liferay SaaS 内のコンテナから提供します。

バッチクライアント拡張機能の JSON リソースは、 batch/ ディレクトリにコピーする必要があります。
fromTask: fromの代わりに、アセンブリステップの前に実行するプロジェクト内の Gradle タスクを指定できます。

たとえば、Spring Boot を使用した マイクロサービス クライアント拡張プロジェクトでは、Gradle タスク bootJar によって、アプリケーションとそのすべての依存関係を含む .jar ファイルが作成されます。この場合、プロパティ fromTask を使用して、プロジェクトの bootJar Gradle タスクの実行をトリガーし、タスクの出力 (つまり、ビルドされた .jar ファイル) を結果の LUFFA のルートに含めます。
```
assemble:
    - fromTask: bootJar
```
プロジェクトの build.gradle ファイルで Gradle exec task を定義することで、ビルドの一部として fromTask を使用して他のコマンドを実行できます (他のプログラミング言語で記述されたコードを構築する場合など)。

例 `組み立て` ブロック

assemble ブロックに複数の from 項目を含めることができます。

assemble:
    - from: build/folder/aaa
      include: "css/*.css"
      into: folder/aaa
    - from: build/folder/bbb
      include: "css/*.css"
      into: folder/bbb

プロジェクトからビルドされていないリソースを含めることもできます。

assemble:
    - from: assets
      into: static

この例では、 [project-root]/somewhere/else にある *.ico ファイルを LUFFA の static フォルダに配置します。

assemble:
    - from: somewhere/else
      include: "*.ico"
      into: static

LUFFA の作成、構造、内容の詳細については、「クライアント拡張機能のパッケージ化」を参照してください。

Liferayインスタンスへのデプロイ

クライアント拡張機能は、展開可能な .zip アーカイブに組み込まれます。各クライアント拡張機能アーカイブには、クライアント拡張機能の設定を含む JSON ファイルが含まれています。

Liferay インストールの正しい場所に .zip ファイルを配置して、クライアント拡張機能をデプロイします。使用する正確なコマンドは、Liferay インスタンスのホスティング方法によって異なります。

Liferay SaaSへのデプロイ

警告

この方法は、Liferay PaaS にクライアント拡張機能をデプロイする際には機能しません。

Liferay SaaSのクライアント拡張機能をデプロイするには、

ワークスペースの client-extensions/ フォルダに移動して、
```
../gradlew clean build
```
コンパイルされた .zip ファイルは、各プロジェクトの dist/ フォルダーに作成されます。一度に 1 つのプロジェクトをビルドするには、プロジェクトのフォルダーからコマンドを実行します。
次のコマンドを実行して、各クライアント拡張機能を選択した環境にデプロイします。
```
lcp deploy --extension [extension-zip-file]
```
プロンプトが表示されたら、プロジェクトとデプロイメント環境を選択します。コマンドが完了すると、zip ファイルが Liferay SaaS プロジェクトにアップロードされます。

Liferay PaaSへのデプロイ

ベータ機能

Liferay PaaS のクライアント拡張ワークフローはベータ機能です。クライアント拡張機能を展開するために使用する前に、次の手順に従ってプロジェクトが適切に構成されていることを確認します。

インフラ 環境に 2 つの CI パイプライン（1 つはコア Liferay Cloud サービス用、もう 1 つはクライアント拡張用）があることを確認します。

。
必要なサービスと Liferay DXP Docker イメージバージョンがあることを確認します。
各環境のLiferay DXPインスタンスに、競合する設定がないことを確認します。
非運用環境では、 Web サーバーサービスを構成して、クライアント拡張機能が基本認証要件をバイパスできるようにします。

重要

Liferay PaaS の非本番環境では、クライアント拡張機能が Liferay DXP で適切に動作し認証されるように特別な設定が必要です。詳細については、「クライアント拡張機能用の Liferay PaaS の設定」を参照してください。

プロジェクトが適切に構成されていることを確認したら、次の手順に従ってクライアント拡張機能をデプロイします。

プロジェクトの Git リポジトリ（Liferay サービスワークスペースの client-extensions/ フォルダ内）にクライアント拡張機能をコミットします。

リポジトリ内の Liferay ワークスペースに client-extensions/ フォルダがない場合は、フォルダを追加して、そこにクライアント拡張機能を配置します。
変更をプッシュし、通常の Liferay PaaS デプロイメントワークフローを使用してビルドを作成します。

クライアント拡張機能では、クライアント拡張機能パイプラインを使用して、他のサービスから独立した、クライアント拡張機能専用のビルドを作成します。ビルドにクライアント拡張サービスとその他のサービスの両方の変更が含まれている場合、2 つの異なるパイプラインによってそれぞれ [ビルド] ページにビルドが作成され、個別にデプロイできます。
ビルドが完了したら、 ビルド ページに移動し、他のビルドと同様にビルドを目的の環境にデプロイします。

他の種類のビルドと同様に、ビルドを環境にデプロイします。

デプロイが完了すると、クライアント拡張機能が新しいサービスとして選択した環境に表示されます。

セルフホスト型Liferayインスタンスへのデプロイ

Liferay インストールをセルフホストする場合は、ワークスペースバンドル zip を使用してクライアント拡張機能をデプロイします。クライアント拡張機能をビルドしてデプロイするには、ワークスペースの client-extensions/ フォルダーから次のコマンドを実行します。

../gradlew clean distBundleZip

zipファイルを手動で展開する必要がある場合は、

../gradlew clean build

次に、各プロジェクトの dist/ フォルダからアーカイブをサーバーの [Liferay Home]/osgi/client-extensions/ フォルダにコピーします。

文脈依存情報

クライアント拡張機能は移植可能です。ドメイン名、ネットワークアドレス、Liferay のドメインなどの環境固有の詳細をハードコードしないでください。クライアント拡張機能は、実行時にコンテキストに関するコンテキスト依存情報を見つけることができます。

すべてのクライアント拡張ワークロードには、重要なコンテキスト依存のメタデータを自動的に含む一連の ルート が提供されます。このルートベースのアプローチにより、アプリケーションロジックは、呼び出される場所に関係なく、コンテキストに応じた情報を均一に取得できます。クライアント拡張プロジェクトのみをこれにポイントする必要があります。

ルート

ルート は、キーと値のペアのセットを含むディレクトリ構造です。ファイル名がキーであり、ファイルの内容が値です。ディレクトリ構造は無視され、ディレクトリパスは環境変数の値になります。これは、 Kubernetes configMapsと同じパターンに従います。

使用する環境変数は、次の 2 種類のルートのいずれかを指すことができます。

LIFERAY_ROUTES_DXP: デプロイされている Liferay 仮想インスタンス の状況依存メタデータを含むルートへのディレクトリパス。

以下は LIFERAY_ROUTES_DXP ルートの例です。

.
# A newline-separated list of every domain belonging to the DXP virtual instance
├── com.liferay.lxc.dxp.domains
# The primary domain ("Virtual Host" field) of the DXP virtual instance
├── com.liferay.lxc.dxp.main.domain
# The protocol with which to communicate with DXP virtual instance (http or https)
└── com.liferay.lxc.dxp.server.protocol

LIFERAY_ROUTES_CLIENT_EXTENSION: クライアント拡張プロジェクト 自体のコンテキスト依存メタデータを含むルートへのディレクトリパス。

例については、 OAuth ヘッドレスサーバークライアント拡張と OAuth ユーザーエージェントクライアント拡張を参照してください。

Liferay Cloud のルートを指定する

Liferay Cloud のコンテナでは、これらの環境変数が自動的に設定されます。ルートは、環境変数によって定義されたパスでコンテナに自動的にマウントされます。

セルフホスト環境でのルートの指定

Liferay Workspace の Exec、 JavaExec、および NodeExec Gradle タスクを使用する場合、これらの環境変数にはデフォルト値が自動的に与えられます。次のデフォルト値が使用されます。

環境変数	デフォルト値
`LIFERAY_ROUTES_DXP`	`[Liferay Home]/routes/default/dxp`
`LIFERAY_ROUTES_CLIENT_EXTENSION`	`[Liferay Home]/routes/default/[Client extension project name]`

環境変数は、Liferay ホームディレクトリとして Liferay ワークスペースの liferay.workspace.home.dir プロパティを使用し、デフォルトの Liferay 仮想インスタンスを示すために default を使用します。これらの環境変数を、 デフォルト ではなく特定の仮想インスタンス ID で定義して、代わりにそれを指すようにします。

注

Liferay ワークスペースのバージョンが 9.0.2 より前の場合は、同じ形式に従ってこれらの環境変数を自分で定義する必要があります。

これら 2 つの環境変数は、メタデータにアクセスするためにクライアント拡張プロセスが呼び出されるときに、クライアント拡張プロセスに提供する必要があります。