ページ読み込みデータアクション

[アーティクル]
07/31/2024

この記事では、Microsoft Dynamics 365 Commerce のページの読み込みデータアクションについて説明します。

表示される各ページ (製品詳細ページ、部門ページ、ホームページなど) にはデータが必要です。ページ読み込みデータアクションは、そのデータを取得するために使用されます。

CreateInput メソッド

ページが読み込まれた後で、createInput メソッドを使用してデータアクションを呼び出すことができます。次の例は、yarn msdyn365 add-data-action DATA_ACTION_NAME コマンドラインインターフェイス (CLI) コマンドを使用して、データアクションの TypeScript ファイルに作成されるサンプルコードを示しています。

const createInput = (args: Msdyn365.ICreateActionContext): Msdyn365.IActionInput => {
    return new GetProductReviewsInput();
};

ICreateActionActionAction タイプは、各 createInput メソッドに渡されるオブジェクトを表します。これには、次の 3 つの情報が含まれています。

要求コンテキスト (inputData.requestContext)
モジュールの構成 (inputData.config)
モジュールのデータ (inputData.data)

次の例では、TypeScript テンプレートファイルの createInput メソッドが createServableDataAction の呼び出しに追加されました。したがって、Dynamics 365 Commerce オンラインソフトウェア開発キット (SDK) は、このデータアクションをページ読み込み時に実行できると判断できます。

export default Msdyn365.createObservableDataAction({
    action: <Msdyn365.IAction<IGetMyDataData>>action,
    input: createInput
});

CreateInput メソッドの例

createInputメソッドに関する次の例として、データアクションと呼ばれるモジュールは、productId という名前のコンフィギュレーションの文字列プロパティを持っています。このプロパティの値は、データアクションが入力として使用する製品 ID です。

/**
 * Creates a ProductInput using module configuration data
 */
const createInput = (inputData: ICreateActionContext<IGeneric<IAny>>): IActionInput => {
    // Ensure module has a config property 'productId'
    if(inputData.config && inputData.config.productId) {
        // Create and return an input for the data action using the module configuration data.
        return new ProductInput(inputData.config.productId);
    }
};

モジュールへのデータアクションの登録

モジュールがページの読み込み時にデータアクションを呼び出す前に、モジュール定義ファイルにデータアクションを登録する必要があります。

次の例では、「get-product」というデータアクションを使用して製品情報をモジュール内に表示できるようなモジュールを示します。

{
    "$type": "moduleDefinition",
    "name": "product-module",
    "friendlyName": "Product module",
    "description": "Product module",
    "categories": ["Product"],
    "dataActions": {
        "product": {
            "path": "../../actions/get-product.action",
            "runOn": "server"
        }
    },
...
}

ここでは、 dataActions ノードは、モジュールがページに読み込まれたときに実行するデータアクションを示します。データアクションオブジェクト内のすべてのキーの名前は、モジュールのデータプロパティ (this.props.data.product プロパティ) で結果が割り当てられるプロパティの名前を参照します。さらに、すべてのデータアクションのパスプロパティは、実行する必要があるデータアクションをエクスポートするファイルをポイントします。通常、データアクションは書き込まれたファイルの既定のエクスポートです。

モジュールビューの開発時に、モジュールを正しく入力するために、登録したデータアクションに基づいて、モジュールデータファイルを対応するタイプで更新する必要があります。次に例を示します。

import { AsyncResult } from '@msdyn365-commerce/retail-proxy';

// product-module.data.ts
export interface IProductModuleData {
    product: AsyncResult<SimpleProduct>;
}

これで、このモジュールを開発すると this.props.data.product プロパティから製品情報にアクセスできます。

クライアント側のレンダリング

Dynamics 365 Commerce はページをサーバー側に表示し、最初の読み込み後にクライアント上に hydrates ページを表示します。モジュール定義で定義されたデータアクションは既定でサーバーで実行され、モジュールはサーバー側で実行されます。モジュールを明示的にクライアントで表示する必要がある場合 runOn パラメーター値を「client」に設定する必要があります。

{
    "$type": "moduleDefinition",
    "name": "product-module",
    "friendlyName": "Product module",
    "description": "Product module",
    "categories": ["Product"],
    "dataActions": {
        "product": {
            "path": "../../actions/get-product.action",
            "runOn": "client"
        }
    },
...
}

メモ

データアクションが、サーバー / クライアントの両方の「runOn」コンフィギュレーションを使用する複数のモジュールで使用されている場合、データアクションはサーバー側でのみ実行されます。したがって、クライアント側でモジュールを明示的に表示する必要がある場合は、runOn の構成の競合を回避することが重要です。

コアデータアクションの登録

Dynamics 365 Commerce オンライン SDK には、一般的な Commerce データタスクの実行に使用できる一連のコアデータアクションが含まれています。データアクションのインターフェイスは、\node_modules\@msdyn365-commerce-modules\retail-actions\dist\lib directory で確認できます。コアデータアクションを登録してモジュール内で使用するには、MODULE_definition.json ファイルの dataActions ノードで次の形式を使用します。

{
    "$type": "contentModule",
    "friendlyName": "Product Feature",
    "name": "product-feature",
    "description": "Feature module used to highlight a product.",
    "categories": [
        "storytelling"
    ],
    "tags": [
        ""
    ],
    "dataActions": {
        "products": {
            "path": "@msdyn365-commerce-modules/retail-actions/dist/lib/get-simple-products",
            "runOn": "server"
        }
    },
    "config": {
        "productIds": {
            "friendlyName": "Product ID",
            "description": "Provide a Product Id that the module will display",
            "type": "string",
            "scope": "module",
            "group": "Content Properties"
        }
    },
    "resources": {
        "resourceKey": {
            "comment": "resource description",
            "value": "resource value"
        }
    }
}

この例では、get-simple-products という名前のコア・データ・アクションを呼び出します。このデータアクションでは、productIds config プロパティを使用して製品 ID の一覧を取得し、 SimpleProduct の結果の配列を返します。次の例では、戻り値を定義するモジュール data.ts ファイルを示します。 SimpleProduct の戻り値の型のインターフェイスは、例の最上部にインポートされる \node_modules\@msdyn365-commerce\commerce-entities\dist ypes\t\commerce-entities ディレクトリで定義されます。

import { AsyncResult, SimpleProduct } from '@msdyn365-commerce/retail-proxy';

export interface IProductFeatureData {
    products: AsyncResult<SimpleProduct>[];
}