次の方法で共有

Commerce Scale Unit API の呼び出し

  • [アーティクル]

この記事では、Microsoft Dynamics 365 Commerce Scale Unit のアプリケーション プログラミング インターフェイス (API) をデータ アクションから、またはモジュール コードから直接呼び出す方法について説明します。

Commerce Scale Unit API を呼び出す場合は、Commerce オンライン ソフトウェア開発キット (SDK) が提供する Retail Server プロキシ ライブラリを使用する必要があります。 このプロキシ ライブラリは、TypeScriptProxy または TSProxy としても知られています。 また、JavaScript ベースまたは TypeScript ベースの環境から Commerce Scale Unit との合理化された通信を可能にします。

Retail Server プロキシのインストール

Retail Server プロキシは Dynamics 365 NPM フィードからダウンロードでき、既定で追加する必要があります。 インストールされていない場合は、package.json ファイルに参照を追加して取得できます。

ソフトウェア開発キット (SDK) の開発環境にプロキシをインストールするには、以下の手順を実行します。

  1. 現在有効なバージョンの Retail Server を決定します。 このバージョンは、バック エンドの拡張性のために使用する Retail Server NuGet パッケージのバージョンになります。

  2. package.json ファイルで、依存関係セクションに次のエントリを追加します。 (このエントリは既に存在し、最新のバージョン情報が含まれる可能性があります。)

    "@msdyn365-commerce/retail-proxy": "{RETAIL_SERVER_VERSION}"

  3. yarn インストールを実行します。

これで、プロジェクトの正しい Retail Server プロキシにアクセスできるようになりました。 モジュール ライブラリの一部として参照が既に含まれている場合があります。

Retail Server プロキシ データ アクション マネージャー

Retail Server プロキシには、HTTP を介して Commerce Scale Unit と内部で通信する一連の API が含まれています。 これらの API は、すべて一連のデータ アクション マネージャーを通じて利用できます。 これらのデータ アクション マネージャーのコードをインポートするには、次のインポート パスを使用します。

// Generic example
import {} from '@msdyn365-commerce/retail-proxy/dist/DataActions/{DATA_ACTION_MANAGER_NAME}.g';

// Specific example
import { getByIdsAsync } from '@msdyn365-commerce/retail-proxy/dist/DataActions/ProductsDataActions.g';

使用できるアクション マネージャーは次のとおりです。

  • CartsDataActions
  • CatalogsDataActions
  • CategoriesDataActions
  • CommerceListsDataActions
  • CustomersDataActions
  • EmployeesDataActions
  • OrgUnitsDataActions
  • PickingListsDataActions
  • ProductsDataActions
  • PurchaseOrdersDataActions
  • RecommendationsDataActions
  • SalesOrdersDataActions
  • ScanResultsDataActions
  • ShiftsDataActions
  • StockCountJournalsDataActions
  • StoreOperationsDataActions
  • SuspendedCartsDataActions
  • TransferOrdersDataActions
  • WarehousesDataActions

各データ アクション マネージャーで使用可能なすべての Retail Server API の一覧については、Commerce Scale Unit の顧客およびコンシューマー API を参照してください。

Retail Server プロキシ データ メソッド

Retail Server プロキシは、データ アクション フレームワークと密接にリンクしています。 したがって、すべての Commerce Scale Unit API に対して、2 つの公開された Retail Server プロキシ メソッドがあります。

  • CreateInput メソッド – このメソッドは IActionInput クラスを作成します。このクラスを使用して、ページ読み込みデータ アクションを実行したり、直接状態を更新したり、actionContext.update() または actionContext.get() メソッドを介してフェッチしたりできます。 このメソッドには常に、create{RETAIL_SERVER_API_NAME}Input という名前が付されます。
  • アクション メソッド – このメソッドは、イベントベースのデータ アクションとして独自に呼び出したり、別のアクション メソッド内に追加してデータ アクション チェーンを作成することができます。 このメソッドには常に、{RETAIL_SERVER_API_NAME}Async という名前が付されます。

ページ読み込み Retail Server プロキシ データ アクションの作成

Retail Server プロキシ API 呼び出しをモジュールに関連付け、ページの読み込み時に実行するには、新しいデータ アクションを作成する必要があります。 このプロセスは、標準のページ読み込みデータ アクションを作成するプロセスと似ています。

この例では、Retail Server プロキシを使用して、ページの読み込み時に構成済みのチャンネルで使用できるすべてのカテゴリを取得するモジュールを作成します。 まず、使用する正しい Commerce Scale Unit プロキシ API を識別する必要があります。 この例では、この API は CategoriesDataActions データ アクション マネージャーによって提供される GetCategories API です。 その後、モジュール定義で使用できるデータ アクションを作成できます。 一般に、このタスクを完了するには、次の 2 つの操作を行う必要があります。

  • 目的の API の Retail Server プロキシcreateInput メソッドを呼び出し、必要なコンテキスト データ (チャネル ID など) を渡す createInput メソッドを指定します。
  • 新しいデータ アクションのアクション メソッドを、Retail Server プロキシによって提供される retailAction メソッドにします。 retailAction メソッドは、渡された入力を解析し、対応する Retail Server プロキシ API を呼び出すように設計されています。

src\actions ディレクトリの下に、新しいデータ アクションのファイルを作成します。 この例では、ファイル名が get-category-list.ts で、次のコードが含まれます。

import { createObservableDataAction, IAction, ICreateActionContext } from '@msdyn365-commerce/core';
import { Category, retailAction } from '@msdyn365-commerce/retail-proxy';
import { createGetCategoriesInput } from '@msdyn365-commerce/retail-proxy/dist/DataActions/CategoriesDataActions.g';

/**
 * Get Org Unit Configuration Data Action
 */
export default createObservableDataAction({
    action: <IAction<Category[]>>retailAction,
    input: (context: ICreateActionContext) => {
        return createGetCategoriesInput({ Paging: { Top: 0 } }, context.requestContext.apiSettings.channelId);
    }
});

get-category-list.ts ファイルは、モジュールに登録できるデータ アクションをエクスポートして、プロジェクト用に構成されたチャネルからすべてのカテゴリのリストを取得します。 この方法では Retail Server との手動通信よりも HTTP 呼び出しのカスタム コードの数がはるかに少なくて済むので、Retail Server プロキシを使用して常に Retail Server を呼び出すことをお勧めします。

次の例は、get-category-list データ アクションをモジュール定義ファイルの"module" > "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"
        },
        "productReviews": {
            "path": "../../actions/getproductreviews",
            "runOn": "server"
        },
        "categories": {
            "path": "../../actions/get-category-list",
            "runOn": "server"
        }
    },
    "config": {
        "imageAlignment": {
            "friendlyName": "Image Alignment",
            "description": "Sets the desired alignment of the image, either left or right on the text.",
            "type": "string",
            "enum": {
                "left": "Left",
                "right": "Right"
            },
            "default": "left",
            "scope": "module",
            "group": "Layout Properties"
        },
        "productTitle": {
            "type": "string",
            "friendlyName": "Product Title",
            "description": "Product placement title"
        },
        "productDetails": {
            "type": "richText",
            "friendlyName": "Product Details",
            "description": "Rich text representing the featured product details"
        },
        "productImage": {
            "type": "image",
            "friendlyName": "Product Image",
            "description": "Image representing the featured product"
        },
        "buttonText": {
            "type": "string",
            "friendlyName": "Button Text",
            "description": "Text to show on the call to action button"
        },
        "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"
        }
    }
}

モジュール data.ts ファイルには、データ アクションの戻り値の型の入力も必要です。 次の例は、サンプル モジュール data.ts ファイルを示しています。 実装後は、this.props.data. オブジェクトを使用してモジュールのビュー ファイルからプロパティにアクセスできます。


import { AsyncResult, Category, SimpleProduct } from '@msdyn365-commerce/retail-proxy';
export interface IProductFeatureData {
    products: AsyncResult<SimpleProduct>[];
    categories: AsyncResult<Category[]>;
}

モジュール コードで Retail Server プロキシ API を直接呼び出す

この例では、Commerce プロキシ getCategoriesAsync ラッパー API を使用して getCategories Commerce API を呼び出す方法を示しています。 この API 呼び出しにより、すべてのカテゴリのリストが返され、サンプル コードによってコンソールにログに記録されます。

import * as React from 'react';

import { getCategoriesAsync } from '@msdyn365-commerce/retail-proxy/dist/DataActions/CategoriesDataActions.g';
import { IProductFeatureData } from './product-feature.data';
import { imageAlignment, IProductFeatureProps} from './product-feature.props.autogenerated';

export interface IProductFeatureViewProps extends IProductFeatureProps<{}> {
    productName: string;
}

/**
 *
 * ProductFeature component
 * @extends {React.PureComponent<IProductFeatureProps<IProductFeatureData>>}
 */
class ProductFeature extends React.PureComponent<IProductFeatureProps<IProductFeatureData>> {
    public render(): JSX.Element | null {
        const {
            config,
        } = this.props;

        // set default product info values from config values if available
        let ProductName = config.productTitle ? config.productTitle : 'No product name defined';

        getCategoriesAsync({ callerContext: this.props.context.actionContext }, this.props.context.request.apiSettings.channelId)
        .then(categoryList2 => {
            let categories2 = '';
            for (let i = 0; i < categoryList2.length; i++) {
                categories2 += `${categoryList2[i].Name}, `;
            }
            console.log(categories2);
        });

        const ProductFeatureViewProps = {
            ...this.props,
            productName: ProductName,
        };

        return this.props.renderView(ProductFeatureViewProps) as React.ReactElement;
    }
}

export default ProductFeature;

追加リソース

データ アクションの概要

データ アクション キャッシュのオプション

モックを使用したデータ アクションのテスト

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

イベント ベースのデータ アクション

コア データ アクション