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

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

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 ファイルでクライアント拡張機能が定義され、ビルドプロセスによって各プロジェクトごとに単一の出力セットが生成されます。構築されたクライアント拡張プロジェクトは、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クライアント拡張機能が定義されています：野球、サッカー、ホッケーです。

使用しているクライアント拡張機能の種類（および実行環境の種類）によっては、他のファイルを使用してクライアント拡張機能の構造やコンテナを設定することもできます。例えば、 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 ブロックは、インクルードするファイルの複数の命令を含めることができる YAML 配列です。各手順書は以下のパターンに従います。

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

アセンブル配列 には、以下の特性があります。

から: クライアント拡張機能アーカイブにファイルをコピーするフォルダーを指定します。
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タスクを定義することで、ビルドの一部としてfromTaskを使って他のコマンドを実行することができます（他のプログラミング言語で書かれたコードのビルドなど）。

例 `組み立て` ブロック

アセンブリ ブロックには、の複数の アイテムを含めることができます。


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ファイルが含まれています。
.zip ファイルを Liferay のインストール場所の適切な場所に配置して、クライアント拡張機能をデプロイします。 使用する具体的なコマンドは、Liferayインスタンスのホスティング方法によって異なります。
Liferay SaaSへのデプロイ


警告


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


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


ワークスペースの client-extensions/ フォルダーに移動して、
../gradlew clean build

コンパイルされた .zip ファイルは、各プロジェクトの dist/ フォルダに作成されます。 プロジェクトを一つずつビルドするには、プロジェクトのフォルダからコマンドを実行してください。


各クライアント拡張機能を選択した環境にデプロイするには、次のコマンドを実行してください。
lcp deploy --extension [extension-zip-file]

指示が表示されたら、プロジェクトとデプロイ環境を選択してください。 コマンドが完了すると、zipファイルがLiferay SaaSプロジェクトにアップロードされます。




注


コンソール経由で多数のクライアント拡張機能を同時にデプロイすると、一時的にAPIリソースの使用量が増える可能性があります。 環境によっては、クライアント拡張機能が有効であっても、デプロイメントが失敗する場合があります。
一括展開が失敗した場合は、クライアント拡張機能を個別に、またはより小さなバッチで展開してください。


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.workspace.home.dir プロパティを使用して Liferay ホーム ディレクトリを指定し、 default を使用してデフォルトの Liferay 仮想インスタンスを指定します。 これらの環境変数を、デフォルトの  の代わりに、特定の仮想インスタンス ID で定義して、それを指すようにします。


注


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


これらの2つの環境変数は、メタデータにアクセスするためにクライアント拡張プロセスが呼び出される際に、クライアント拡張プロセスに提供されなければなりません。
関連トピック

バッチクライアント拡張機能
コードとしての構成
フロントエンドクライアント拡張機能
マイクロサービスのクライアント拡張
パッケージングクライアント拡張機能

チュートリアル

JavaScriptクライアント拡張の使用
CSSクライアント拡張の使用


					
							
								
									Capability:
								
									
										
											Development and Tooling
										
									
							
							
								
									Resource Type:
								
									
										
											Official Documentation
										
									
							
							
								
									Feature:
								
									
										
											Client Extensions
										
									
							
							
								
									Deployment Approach:
								
									
										
											Liferay SaaS
										
									
									
										
											Liferay Self-Hosted

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