Documentation

新しい配送エンジンの実装

このチュートリアルでは、 CommerceShippingEngine インターフェイスを実装して、カスタムの配送エンジンを追加する方法を示します。

配送エンジンは配送オプションを処理して、ユーザーに表示されるオプション(価格など)を決定します。 Liferay Commerceには標準で次の3つの配送エンジンが組み込まれています: flat rate enginevariable rate engineFedEx engine

FedEx配送エンジンは、Commerce Enterpriseの加入者のみが利用できます。

すぐに使える配送方法

サンプルをデプロイする

このセクションでは、配送エンジンをLiferay Commerceのインスタンスで実行する例を示します。 次の手順を実行します:

  1. Liferay Commerceを開始します。

    docker run -it -p 8080:8080 liferay/portal:7.4.3.22-ga22
    
  2. Acme Commerce Shipping Engine をダウンロードして解凍します。

    curl https://learn.liferay.com/commerce/latest/en/developer-guide/sales/liferay-j6x8.zip -O
    
    unzip liferay-j6x8.zip
    
  3. サンプルをビルドしてデプロイします。

    ./gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
    

    注釈

    このコマンドは、デプロイされたjarをDockerコンテナの /opt/liferay/osgi/modulesにコピーするのと同じです。

  4. Dockerコンテナコンソールでデプロイを確認します。

    STARTED com.acme.j6x8.impl_1.0.0
    
  5. サンプルの配送エンジンが追加されたことを確認します。 ブラウザでhttps://localhost:8080を開きます。 次に、アプリケーションメニュー(Applications Menu)をクリックし、[コマース]→[チャネル]に移動します。 配送方法のセクションには、当社の配送エンジンを代表する新しい配送方法(「割引レート」)が表示されます。

注釈

Commerce 2.1以前のバージョンでは、サイト管理Commerce設定配送方法に移動して、配送方法を確認します。

新しい配送方法

これで、CommerceShippingEngineを実装する新しい配送エンジンを正常に構築およびデプロイできました。

次に、詳細をさらに詳しく見ていきましょう。

例の説明

このセクションでは、デプロイした例について確認します。 最初に、OSGi登録用のクラスに注釈を付けます。 次に、 CommerceShippingEngineインターフェイスを確認します。 最後に、CommerceShippingEngineの実装を完了します。

OSGi登録用のクラスに注釈を付ける

@Component(
    property = "commerce.shipping.engine.key=j6x8",
    service = CommerceShippingEngine.class
)
public class J6X8CommerceShippingEngine implements CommerceShippingEngine {

Liferay Commerceが、 配送エンジンレジストリ で新しいエンジンを他のエンジンと区別できるように、配送エンジンに個別のキーを提供することが重要です。 すでに使用されているキーを再利用すると、既存の関連付けられているエンジンが上書きされます。

CommerceShippingEngineインターフェイスを確認する

次のメソッドを実装します。

public String getCommerceShippingOptionLabel(String name, Locale locale);

このメソッドは、配送オプションに使用されるテキストラベルを返します。 言語キーで説明を取得する際のリファレンスについては、J6X8CommerceShippingEngine.javaの実装を参照してください。

詳細は、 アプリケーションのローカライズ を参照してください。

public List<CommerceShippingOption> getCommerceShippingOptions(
        CommerceContext commerceContext, CommerceOrder commerceOrder,
        Locale locale)
    throws CommerceShippingEngineException;

ここで、カスタム配送エンジンのビジネスロジックを追加します。 利用可能なオプションのリストを取得し、それらを顧客に提示するために必要な処理を実行する必要があります。

public String getDescription(Locale locale);

これは、配送エンジンの簡単な説明を返します。 このメソッドは、getCommerceShippingOptionLabelメソッドと同様に動作します。

public String getName(Locale locale);

これは、UIに表示する配送エンジンの名前を返します。 また、getCommerceShippingOptionLabelおよびgetDescriptionメソッドと同様に動作します。

配送エンジンを完成させる

配送エンジンのメソッド getCommerceShippingOptions は、顧客に表示する配送オプションのリストを返します。

@Override
public List<CommerceShippingOption> getCommerceShippingOptions(
        CommerceContext commerceContext, CommerceOrder commerceOrder,
        Locale locale)
    throws CommerceShippingEngineException {

    try {
        CommerceShippingMethod commerceShippingMethod =
            _commerceShippingMethodLocalService.fetchCommerceShippingMethod(
                commerceOrder.getScopeGroupId(), "j6x8");

        if (commerceShippingMethod == null) {
            return Collections.emptyList();
        }

        List<CommerceShippingOption> commerceShippingOptions =
            new ArrayList<>();

        List<CommerceShippingFixedOption> commerceShippingFixedOptions =
            _commerceShippingFixedOptionLocalService.
                getCommerceShippingFixedOptions(
                    commerceShippingMethod.getCommerceShippingMethodId(),
                    QueryUtil.ALL_POS, QueryUtil.ALL_POS);

        for (CommerceShippingFixedOption commerceShippingFixedOption :
                commerceShippingFixedOptions) {

            CommerceAddress commerceAddress =
                commerceOrder.getShippingAddress();

            if (_commerceAddressRestrictionLocalService.
                    isCommerceShippingMethodRestricted(
                        commerceShippingFixedOption.
                            getCommerceShippingMethodId(),
                        commerceAddress.getCommerceCountryId())) {

                continue;
            }

            String name = commerceShippingFixedOption.getName(locale);

            if (_commerceShippingHelper.isFreeShipping(commerceOrder)) {
                commerceShippingOptions.add(
                    new CommerceShippingOption(
                        name, name, BigDecimal.ZERO));
            }

            BigDecimal amount = commerceShippingFixedOption.getAmount();

            amount = amount.multiply(BigDecimal.valueOf(0.75));

            commerceShippingOptions.add(
                new CommerceShippingOption(name, name, amount));
        }

        return commerceShippingOptions;
    }
    catch (Exception exception) {
        throw new CommerceShippingEngineException(exception);
    }
}

この方法では、まず利用可能な配送オプションを取得し、それらをループさせて各配送オプションを処理します。

CommerceShippingMethod commerceShippingMethod =
    _commerceShippingMethodLocalService.fetchCommerceShippingMethod(
        commerceOrder.getScopeGroupId(), "j6x8");

if (commerceShippingMethod == null) {
    return Collections.emptyList();
}

List<CommerceShippingOption> commerceShippingOptions =
    new ArrayList<>();

List<CommerceShippingFixedOption> commerceShippingFixedOptions =
    _commerceShippingFixedOptionLocalService.
        getCommerceShippingFixedOptions(
            commerceShippingMethod.getCommerceShippingMethodId(),
            QueryUtil.ALL_POS, QueryUtil.ALL_POS);

for (CommerceShippingFixedOption commerceShippingFixedOption :
        commerceShippingFixedOptions) {

    //The shipping option processing logic goes here.

まず、 CommerceShippingMethodLocalService を使用して「配送方法」(配送エンジンを表す)を取得し、次に CommerceShippingFixedOptionLocalService を使用して利用可能なオプションを取得します。

その後、配送方法をループさせて処理します。

配送オプションの処理手順は次のとおりです。

Liferay Commerceの 固定料金配送エンジン は、開始するのに適したベースラインとなる処理ステップを確認するのに適したリファレンスです。 この例では、同様の手順を採用しています。

アドレス制限チェックを実装する

private boolean _shippingOptionIsAddressRestricted(
        CommerceOrder commerceOrder,
        CommerceShippingFixedOption commerceShippingFixedOption)
    throws PortalException {

    CommerceAddress commerceAddress = commerceOrder.getShippingAddress();

    return _commerceAddressRestrictionLocalService.
        isCommerceShippingMethodRestricted(
            commerceShippingFixedOption.getCommerceShippingMethodId(),
            commerceAddress.getCommerceCountryId());
}

次のステップでは、特定の配送オプションが注文の配送先住所に対して制限されているかどうかを判断します。 制限されたオプションは、選択するオプションとして表示されません。

CommerceAddressRestrictionLocalService を使用して、オプションが注文の住所に制限されているかどうかを判断します。 アドレス情報を取得するには、CommerceOrderを使用します。CommerceOrderオブジェクトは、出荷される注文に関するすべての種類の情報を表します。 CommerceOrderで使用できる他のメソッドについては、 CommerceOrder.javaCommerceOrderModel.java を参照してください。

送料無料の有無を確認する。

String name = commerceShippingFixedOption.getName(locale);

if (_commerceShippingHelper.isFreeShipping(commerceOrder)) {
    commerceShippingOptions.add(
        new CommerceShippingOption(
            name, name, BigDecimal.ZERO));
}

CommerceShippingHelper を使用して、注文を無料にする必要があるかどうかをより簡単に判断できます。

カスタム配送オプションロジックを追加する。

BigDecimal amount = commerceShippingFixedOption.getAmount();

amount = amount.multiply(BigDecimal.valueOf(0.75));

ここでは、配送オプションのロジックを追加することができます。 この例の配送オプションでは、標準の固定配送オプションの金額が25%減額されます。

処理済みの配送オプションを追加する。

commerceShippingOptions.add(
    new CommerceShippingOption(name, name, amount));
} // end of shipping option processing loop

return commerceShippingOptions;

その金額を配送オプションに適用し、配送オプションをリストに追加します。 その後、forループを閉じて、配送オプションのリストを返します。

言語キーを Language.propertiesに追加します。

モジュール内のLanguage.propertiesファイルに言語キーとその値を追加します。

discounted-rate=Discounted Rate
ship-for-a-discounted-price=Ship for a discounted price.

詳細は、 アプリケーションのローカライズ を参照してください。

まとめ

CommerceShippingEngineインターフェイスを実装するための基本を理解し、Liferay Commerceに新しい配送エンジンを追加しました。