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

Shipping Engineクライアント拡張機能の使用

Liferay DXP 2024.Q1+/Portal GA112+

クライアント拡張機能を使用すると、Liferayに新しい配送エンジンを追加できます。サンプルワークスペース のこのクライアント拡張機能は、OAuth 2 を使用して Liferay と通信するスタンドアロンの Spring Boot アプリケーションで構成されています。 Liferay で標準で利用できる配送方法の詳細については、 配送方法の設定 を参照してください。

前提条件

  1. サポートされているバージョンの Java をインストールしてください。

    注記

    推奨される JVM 設定については、 JVM 構成 を参照してください。

  2. サンプルワークスペースをダウンロードして解凍してください。

    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

    unzip -d liferay-sample-workspace com.liferay.sample.workspace-latest.zip

これで、Liferay にクライアント拡張機能を起動してデプロイするためのツールが揃いました。

Shipping Engineクライアント拡張機能を調べます

client-extensions/liferay-sample-commerce-shipping-engine/client-extension.yaml ファイルは、サンプルワークスペース内の配送エンジンのクライアント拡張機能を定義します。 .yaml ファイルには、理解しておくべき重要なブロックが 3 つあります。

assemble:
    - fromTask: bootJar

assemble ブロックは、スタンドアロンのアプリケーション/マイクロサービスが bootJar コマンドで作成されることを指定しています。これは Spring Boot Gradle プラグイン から入手できます。 Liferay SaaSにデプロイするには、アプリケーションのJARファイルをLUFFAに含める必要があります。

liferay-sample-commerce-shipping-engine:
   key: liferay-sample-commerce-shipping-engine
   name: Liferay Sample Commerce Shipping Engine
   oAuth2ApplicationExternalReferenceCode: liferay-sample-commerce-shipping-engine-oaua
   shippingEngineTypeSettings:
      key1: value1
      key2: value2
      key3: value3
      key4: value4
      key5: value5
   type: commerceShippingEngine

liferay-sample-commerce-shipping-engine ブロックには、配送エンジンのクライアント拡張に必要なキー構成が含まれています。各フィールドの詳細については、 Shipping Engine Client Extension YAML Reference を参照してください。

liferay-sample-commerce-shipping-engine-oaua:
   .serviceAddress: localhost:58081
   .serviceScheme: http
   name: Liferay Sample Commerce Shipping Engine OAuth Application User Agent
   scopes:
      - Liferay.Headless.Admin.Workflow.everything
   type: oAuthApplicationUserAgent

client-extension.yaml のもう 1 つの重要な部分は、 liferay-sample-commerce-shipping-engine-oaua 定義にあります。 serviceAddress パラメータは、サービスがローカルで実行される場所を定義し、 serviceScheme パラメータはプロトコルを定義します。 name フィールドは、OAuth アプリケーションのユーザー エージェントの名前を定義します。スコープ フィールドは、ヘッドレス API に与えられるアクセスを定義します。このセクションでは、Liferayを認証サーバーとして設定します。これにより、次にデプロイする配送エンジンがリソースサーバーのセキュアなエンドポイントを呼び出し、ペイロードを送信できるようになります。詳細については、 OAuth ユーザーエージェント YAML 設定リファレンス を参照してください。

Shipping Engineクライアント拡張機能をデプロイする

  1. サンプルワークスペースに移動してください。

  2. 走る

    ./gradlew initBundle

    これにより、ワークスペースの /bundles フォルダー内にバンドルがダウンロードされます。

  3. /bundles/tomcat/bin フォルダに移動します。走る

    ./catalina run

  4. サンプルワークスペースの /client-extensions/liferay-sample-commerce-shipping-engine フォルダーに戻ります。

  5. 走る

    ../../gradlew clean createClientExtensionConfig deploy

  6. Liferayのログで、クライアント拡張機能がデプロイされ、起動したことを確認してください。

    2024-02-23 11:41:03.277 INFO  [com.liferay.portal.kernel.deploy.auto.AutoDeployScanner][AutoDeployDir:212] Processing liferay-sample-commerce-shipping-engine.zip
2024-02-23 11:41:13.918 INFO  [fileinstall-directory-watcher][BundleStartStopLogger:68] STARTED liferaysamplecommerceshippingengine_7.4.13 [1504]

    さらに、OAuthユーザーエージェントに関するメッセージもログに記録されます。

    2024-02-23 11:41:14.066 INFO  [CM Event Dispatcher (Fire ConfigurationEvent: pid=com.liferay.oauth2.provider.configuration.OAuth2ProviderApplicationUserAgentConfiguration~liferay-sample-commerce-shipping-engine-oaua)][InterpolationConfigurationPlugin:135] Replaced value of configuration property 'homePageURL' for PID com.liferay.oauth2.provider.configuration.OAuth2ProviderApplicationUserAgentConfiguration~liferay-sample-commerce-shipping-engine-oaua
2024-02-23 11:41:14.099 INFO  [CM Event Dispatcher (Fire ConfigurationEvent: pid=com.liferay.oauth2.provider.configuration.OAuth2ProviderApplicationUserAgentConfiguration~liferay-sample-commerce-shipping-engine-oaua)][OAuth2ProviderApplicationUserAgentConfigurationFactory:170] OAuth 2 application with external reference code liferay-sample-commerce-shipping-engine-oaua and company ID 44408322414245 has client ID id-536a55dd-89fb-f483-b719-328270d95199

  7. OAuthアプリケーションユーザーエージェントがLiferayに追加されていることを確認してください。コントロール パネル → OAuth2 管理 に移動します。

Liferay Sample Commerce Shipping Engine OAuth Application User Agentは、クライアント拡張機能をデプロイする際に自動的に追加されます。

Liferay Sample Commerce Shipping Engine OAuth Application User Agent は、Liferay が保護されたエンドポイントを介して Spring Boot アプリケーションのデータにアクセスするために必要な OAuth 2 認証 を提供します。この場合、Liferayがアプリケーションを認証するために必要なのは、 application-default.properties に外部参照コードを宣言することだけです。

liferay.oauth.application.external.reference.codes=liferay-sample-commerce-shipping-engine-oaua

マイクロサービスを開始する

client-extensions/liferay-sample-commerce-shipping-engine フォルダーから、以下を実行します。

../../gradlew bootRun

Spring Bootアプリケーションが起動し、ログにメッセージを出力します。

...
2024-02-28 09:44:17.880  INFO 4363 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 58081 (http) with context path ''
2024-02-28 09:44:17.887  INFO 4363 --- [           main] c.l.sample.SampleSpringBootApplication   : Started SampleSpringBootApplication in 2.32 seconds (JVM running for 2.62)
<==========---> 80% EXECUTING [56s]
> :client-extensions:liferay-sample-commerce-shipping-engine:bootRun

出荷エンジンの追加を確認する

  1. 管理者としてログインし、 グローバルメニュー (Applications Menu icon) を開き、 コントロールパネル → サイト に移動します。

  2. 新しいMiniumサイトを追加します。

  3. グローバルメニュー (Applications Menu icon) を開き、 コマース → チャネル に移動します。

  4. ミニウムポータル を選択し、配送方法のセクションまでスクロールします。新しい配送エンジンが追加されたことをここで確認してください。デフォルトでは無効になっています。

    チャネル設定で新しい配送エンジンが追加されていることを確認してください。

  5. 新しい配送エンジンを選択し、 アクティブ トグルを使用して有効化します。

  6. をクリックして保存します。配送エンジン用に新しい 設定 タブが表示されます。設定タブには入力フィールドがあります。クライアント拡張機能自体に値を直接記述する代わりに、ここにクライアント拡張機能に必要な情報を入力できます。この例には、サンプルとなるキーと値のペアが含まれています。

  7. をクリックして保存します。

  8. サイトを開き、アカウント選択機能を使って新しいアカウントを作成してください。

  9. カートに商品をいくつか追加してください。

  10. ミニカートを開いて、 送信 をクリックします。これでチェックアウトの流れが開始されます。

  11. 配送オプションを選択するステップに到達するまで、チェックアウト手続きを続けてください。

    新しく追加されたクライアント拡張機能から、2つの新しい配送オプションが追加されたことを確認します。

  12. クライアント拡張機能から2つの新しいオプションのいずれかを選択し、注文を完了してください。

法典の検証

Liferayで配送エンジンを作成するには、以下の詳細情報が必要です。

  • 鍵
  • 名前
  • 説明
  • 配送オプション
  • 有効な配送オプション
  • 配送オプションラベル

提供されているサンプル配送エンジンクライアント拡張機能には、Spring Bootアプリケーションによって呼び出され、Liferayに新しい配送エンジンを作成するための複数のコントローラーが含まれています。 client-extension.yaml ファイル内の キー フィールドは、出荷エンジンのキーを指定します。既存の配送方法と競合しない、固有のキーを使用してください。

NameRestController.java を検査中

@PostMapping
public ResponseEntity<String> post(
   @AuthenticationPrincipal Jwt jwt, @RequestBody String json) {

   log(jwt, _log, json);

   return new ResponseEntity<>(
      new JSONObject(
      ).put(
         "name", "Shipping Engine Name"
      ).toString(),
      HttpStatus.OK);
}

NameRestController には、JSON Web Token (JWT) とリクエストボディの 2 つのパラメータを持つ単一の POST メソッドが含まれています。トークンはHTTP呼び出しを認証し、リクエストボディにはJSON形式の文字列としてデータが含まれます。リクエストボディをログに記録した後、 JSONObject() コンストラクタを使用して配送エンジンの名前を追加し、HTTP ステータスとともにレスポンス エンティティとして返します。

DescriptionRestController.java を検査中

@PostMapping
public ResponseEntity<String> post(
   @AuthenticationPrincipal Jwt jwt, @RequestBody String json) {

   log(jwt, _log, json);

   return new ResponseEntity<>(
      new JSONObject(
      ).put(
         "description", "Shipping Engine Description"
      ).toString(),
      HttpStatus.OK);
}

DescriptionRestController には、JSON Web Token (JWT) とリクエストボディの 2 つのパラメータを持つ単一の POST メソッドが含まれています。トークンはHTTP呼び出しを認証し、リクエストボディにはJSON形式の文字列としてデータが含まれます。リクエストボディをログに記録した後、 JSONObject() コンストラクタを使用して配送エンジンの説明を追加し、HTTP ステータスとともにレスポンス エンティティとして返します。

OptionLabelRestController.java を検査しています

@PostMapping
public ResponseEntity<String> post(
      @AuthenticationPrincipal Jwt jwt, @RequestBody String json)
   throws Exception {

   log(jwt, _log, json);

   JSONObject jsonObject = new JSONObject(json);

   if (!jsonObject.has("name")) {
      return null;
   }

   return new ResponseEntity<>(
      new JSONObject(
      ).put(
         "name", "Shipping Option Name"
      ).toString(),
      HttpStatus.OK);
}

OptionLabelRestController には、JSON Web Token (JWT) とリクエストボディの 2 つのパラメータを持つ単一の POST メソッドが含まれています。トークンはHTTP呼び出しを認証し、リクエストボディにはJSON形式の文字列としてデータが含まれます。リクエストボディをログに記録した後、 JSONObject() コンストラクタを使用して、リクエストボディ内の JSON 文字列から新しい JSON オブジェクトを作成します。 JSON オブジェクトに name 属性が含まれていない場合、null が返されます。次に、 JSONObject() コンストラクタを使用して配送オプション名を追加し、HTTP ステータスとともにレスポンス エンティティとして返します。

OptionsRestController.java を検査中

@PostMapping
public ResponseEntity<String> post(
      @AuthenticationPrincipal Jwt jwt, @RequestBody String json)
   throws Exception {

   log(jwt, _log, json);

   return new ResponseEntity<>(
      new JSONObject(
      ).put(
         "shippingOptions",
         new JSONArray(
         ).put(
            new JSONObject(
            ).put(
               "amount", 13.90
            ).put(
               "key", "CXOption1"
            ).put(
               "name", "CXOption1"
            ).put(
               "priority", 1
            )
         ).put(
            new JSONObject(
            ).put(
               "amount", 15.99
            ).put(
               "key", "CXOption2"
            ).put(
               "name", "CXOption2"
            ).put(
               "priority", 2
            )
         ).put(
            new JSONObject(
            ).put(
               "amount", 17.50
            ).put(
               "key", "CXOption3"
            ).put(
               "name", "CXOption3"
            ).put(
               "priority", 3
            )
         )
      ).toString(),
      HttpStatus.OK);
}

OptionsRestController には、JSON Web Token (JWT) とリクエストボディの 2 つのパラメータを持つ単一の POST メソッドが含まれています。トークンはHTTP呼び出しを認証し、リクエストボディにはJSON形式の文字列としてデータが含まれます。リクエストボディをログに記録した後、 JSONObject() コンストラクタに続いて JSONArray() コンストラクタを使用して、3 つの配送オプションを配送エンジンに追加し、HTTP ステータスとともにレスポンス エンティティとして返します。各配送オプションには、 キー、 名前、 優先度、および 金額 が必要です。

OptionsEnabledRestController.java を検査しています

@PostMapping
public ResponseEntity<String> post(
      @AuthenticationPrincipal Jwt jwt, @RequestBody String json)
   throws Exception {

   log(jwt, _log, json);

   return new ResponseEntity<>(
      new JSONObject(
      ).put(
         "shippingOptions",
         new JSONArray(
         ).put(
            new JSONObject(
            ).put(
               "amount", 13.90
            ).put(
               "key", "CXOption1"
            ).put(
               "name", "CXOption1"
            ).put(
               "priority", 1
            )
         ).put(
            new JSONObject(
            ).put(
               "amount", 15.99
            ).put(
               "key", "CXOption2"
            ).put(
               "name", "CXOption2"
            ).put(
               "priority", 2
            )
         )
      ).toString(),
      HttpStatus.OK);
}

OptionsEnabledRestController には、JSON Web Token (JWT) とリクエストボディの 2 つのパラメータを持つ単一の POST メソッドが含まれています。トークンはHTTP呼び出しを認証し、リクエストボディにはJSON形式の文字列としてデータが含まれます。リクエストボディをログに記録した後、 JSONObject() コンストラクタに続いて JSONArray() コンストラクタを使用して、2 つの配送オプションを配送エンジンに追加し、HTTP ステータスとともにレスポンス エンティティとして返します。これらは、チェックアウト時に選択可能な有効な配送オプションです。各配送オプションには、 キー、 名前、 優先度、および 金額 が必要です。

Capability:
Commerce
Development and Tooling
Resource Type:
Official Documentation
Feature:
Client Extensions
Developer Tools
Java Development
Deployment Approach:
Liferay PaaS
Liferay SaaS
Liferay Self-Hosted