Pricing Entity Views and Actions API の操作

概要

Sitecore XC Pricing Entity Views and Actions API を使用して価格設定関連情報を交換する方法。

外部システムは、Commerce Views サービスに基づくオーサリング API である Entity Views and Actions API を使用して価格設定関連の情報を交換できます。

このに示すように、(C# を使用して) コンテナー呼び出し内に Commerce Engine の操作とコマンドを含める必要があります。

Sitecore Experience Commerce (XC) システムで操作を実行するには、呼び出し側システムが最初に Sitecore Identity Server から有効なベアラー認証トークンを取得する必要があります。

注記

Views and Actions API はビジネス ユーザー インターフェイスにサービスを提供するように設計された Authoring API であり、統合シナリオ用には最適化されていません。

Commerce 統合に Views and Actions API を使用する場合は、次の点を考慮する必要があります。

  • Views and Actions API は一度に 1 つの Commerce エンティティのみを処理できます。バッチ処理はサポートしていません。

  • Views and Actions API は、Commerce Web サービス API よりも大きなオーバーヘッドが伴います。Views and Action API の呼び出しは、通常 3 ステップのプロセスであり、アクションのビューの取得、更新された値によるビューのプロパティの変更、アクションの実行が必要です。

XC Pricing View Actions API は、プライス ブックに関連するカタログを追加取得編集、および管理するアクションを提供します。

Views and Actions API を使用してプライス ブックを使用できます。プライス ブックを追加するときは、次の点に注意してください。

  • プライス ブックの名前は一意です。

  • プライス ブックを作成すると、その名前は変更できません。

  • プライス ブックは削除できません。

プライス ブックを追加するには:

  1. アクションのエンティティ ビューを取得します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView(string.Empty, "Details", "AddPriceBook", string.Empty);
    EntityView view = Proxy.GetValue(query);
  2. ビューのプロパティを変更します。少なくとも、Name プロパティの値を指定する必要があります。他のすべてのビュー プロパティはオプションです。次の例では、クエリにすべてのプロパティの値が含まれています。

    var nameProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Name"));
    nameProperty.Value = "MyPriceBook";
    var displayNameProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("DisplayName"));
    displayNameProperty.Value = "Book Display Name";
    var descriptionProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Description"));
    descriptionProperty.Value = "Book Description";
    var currencySetProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("CurrencySetId"));
    currencySetProperty.Value = "{0F65742E-317F-44B0-A4DE-EBF06209E8EE}";
  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

    応答は、PriceBookAdded モデルでプライス ブックのフレンドリ ID を返します。次に例を示します。

    PriceBookAdded priceBookAddedModel = command.Models.OfType<PriceBookAdded>().FirstOrDefault();
    string bookFriendlyId = priceBookAddedModel?.PriceBookFriendlyId;

Pricing Entity Views and Actions API を使用して、さまざまなプライス ブックのビューを取得できます。プライス ブックは複合エンティティ ビューを使用します。プライス ブックの Master ビューをクエリした場合、応答は子ビュー (たとえば、DetailsPriceBookCatalogs、および PriceCards 子ビュー) も返します。子ビューは個別にクエリできます。子ビューは、他の子ビューの親になることもできます。

  • プライス ブックのマスター ビューを取得するには、次のように指定します。

    DataServiceActionQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceBook-{bookFriendlyId}", "Master", string.Empty, string.Empty);
    EntityView view = Proxy.GetValue(query);
  • たとえば、プライス ブックの子ビュー、詳細ビュー、関連するカタログ ビュー、またはプライス カード ビューを取得するには、次のように指定します。

    // getting the book's details view
    query = container.GetEntityView($"Entity-PriceBook-{bookFriendlyId}", "Details", string.Empty, string.Empty);
    view = Proxy.GetValue(query);
    
    // getting the book's associated catalogs view
    query = container.GetEntityView($"Entity-PriceBook-{bookFriendlyId}", "PriceBookCatalogs", string.Empty, string.Empty);
    view = Proxy.GetValue(query);
    
    // getting the book's cards view
    query = container.GetEntityView($"Entity-PriceBook-{bookFriendlyId}", "PriceCards", string.Empty, string.Empty);
    view = Proxy.GetValue(query);

(C#) を使用したプライス ブックの編集

Pricing Entity Views and Actions API を使用して、プライス ブックの表示名、説明、および通貨セットのプロパティを変更できます。これらのプロパティのいずれかに新しい値を指定しない場合、現在の値は変更されません。

プライス ブックのプロパティを変更するには:

  1. アクションのエンティティ ビューを取得します。次に例を示します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceBook-{bookFriendlyId}", "Details", "EditPriceBook", string.Empty)
    EntityView view = Proxy.GetValue(query);
  2. 必要に応じてビューのプロパティを変更します。次に例を示します。

    var displayNameProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("DisplayName"));
    displayNameProperty.Value = "Edited Book Display Name";
    var descriptionProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Description"));
    descriptionProperty.Value = "Edited Book Description";
    var currencySetProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("CurrencySetId"));
    currencySetProperty.Value = "{0F65742E-317F-44B0-A4DE-EBF06209E8EE}";
  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

プライス ブックへのカタログの関連付け (C#)

Pricing Views and Actions API を使用して、カタログをプライス ブックに関連付け、プライス カードをカタログ アイテムに適用できます。同じプライス ブックを複数のカタログに関連付けることができますが、カタログを関連付けられるプライス ブックは 1 つのみです。

プライス ブックにカタログを関連付けるには:

  1. アクションのエンティティ ビューを取得します。次に例を示します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceBook-{bookFriendlyId}", "PriceBookCatalogs", "AssociateCatalog", string.Empty);
    EntityView view = Proxy.GetValue(query);
  2. ビューのプロパティを変更します。次に例を示します。

    var catalogProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("CatalogName"));
    catalogProperty.Value = "MyCatalog";
  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

プライス ブックからのカタログの関連付け解除 (C#)

カタログ内で定義された販売可能アイテムにプライス カードを適用する必要がなくなった場合は、プライス ブックからカタログの関連付けを解除できます。

プライス ブックの関連付けを解除するには:

  1. アクションのエンティティ ビューを取得します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceBook-{bookFriendlyId}", string.Empty, "DisassociateCatalog", string.Empty);
    EntityView view = Proxy.GetValue(query);
  2. ビューのプロパティを変更します。次に例を示します。view.ItemId = "MyCatalog";

  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

Pricing Views and Actions API を使用して、プライス カードの addgeteditduplicate、および delete アクションを実行できます。

指定したプライス ブック内にプライス カードを作成できます。プライス カードの名前は、プライス ブック内で一意である必要があります。作成後にプライス カードの名前を変更することはできません。

プライス カードを作成するには:

  1. アクションのエンティティ ビューを取得します。次に例を示します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceBook-{bookFriendlyId}", "Details", "AddPriceCard", string.Empty);
    EntityView view = Proxy.GetValue(query);
  2. ビューのプロパティを変更します。少なくとも、"Name" プロパティの値を指定する必要があります。オプションで、他のプロパティの値を指定できます。次に例を示します。

    var nameProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Name"));
    nameProperty.Value = "MyPriceCard";
    var displayNameProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("DisplayName"));
    displayNameProperty.Value = "Card Display Name";
    var descriptionProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Description"));
    descriptionProperty.Value = "Card Description";
  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

    応答は、PriceCardAdded モデルを使用してプライス カードに適した ID を返します。次に例を示します。

    PriceCardAdded priceCardAddedModel = command.Models.OfType<PriceCardAdded>().FirstOrDefault();
    string cardFriendlyId = priceCardAddedModel?.PriceCardFriendlyId;

Pricing Views and Actions API を使用して、さまざまなプライス カードのビューを取得できます。プライス カードのビューは複合エンティティ ビューとして実装されます。プライス カードの Master ビューをクエリした場合、応答はその子ビュー (たとえば、プライス カードの DetailsPriceSnapshots 子ビュー) を返します。

子ビューを個別にクエリすることもできます。子ビューは、独自の子ビューを定義できます。

  • プライス カードのマスター ビューを取得するには、次のように指定します。

    DataServiceActionQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceCard-{cardFriendlyId}", "Master", string.Empty, string.Empty);
    EntityView view = Proxy.GetValue(query);
  • プライス カードの子ビュー、たとえば "Details" ビューと "PriceSnapShots" ビューをそれぞれ個別に取得するには、次のように指定します。

    // getting the card's details view
    query = container.GetEntityView($"Entity-PriceCard-{cardFriendlyId}", "Details", string.Empty, string.Empty);
    view = Proxy.GetValue(query);
    
    // getting the card's snapshots view
    query = container.GetEntityView($"Entity-PriceCard-{cardFriendlyId}", "PriceCardSnapshots", string.Empty, string.Empty);
    view = Proxy.GetValue(query);
    

Pricing Views and Actions API を使用して、既存のプライス カードの DisplayName プロパティと Description プロパティを変更できます。nameプロパティ (プライス カードの内部名) は変更できません。プロパティに新しい値を指定しない場合、その現在の値は変更されません。

プライス カードを編集するには:

  1. アクションのエンティティ ビューを取得します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceBook-{bookFriendlyId}", "Details", "EditPriceBook", string.Empty)
    EntityView view = Proxy.GetValue(query);
  2. ビューのプロパティを設定します。次に例を示します。

    var displayNameProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("DisplayName"));
    displayNameProperty.Value = "Edited Book Display Name";
    var descriptionProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Description"));
    descriptionProperty.Value = "Edited Book Description";
    var currencySetProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("CurrencySetId"));
    currencySetProperty.Value = "{0F65742E-317F-44B0-A4DE-EBF06209E8EE}";
  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

Views and Actions API を使用して、既存のプライス カードを複製し、同じプライス ブック内に新しいプライス カードを作成できます。複製したプライス カードのプライス スナップショットは、draft ステータスに設定されています。

プライス カードを複製するには:

  1. アクションのエンティティ ビューを取得します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceCard-{cardFriendlyId}", "Details", "DuplicatePriceCard", string.Empty);
    EntityView view = Proxy.GetValue(query);
  2. 新しいプライス カードの名前を指定して、ビューのプロパティを変更します。次に例を示します。

    注記

    プライス カードの名前は、プライス ブック内で一意である必要があります。

    var nameProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("DuplicateCardName"));
    nameProperty.Value = "MyDuplicatePriceCard";
  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

Views and Actions API を使用して、プライス ブックからプライス カードを削除できます。

注記

承認されたプライス スナップショットを含むプライス カードは削除できません。

プライス カードを削除するには:

  1. アクションのエンティティ ビューを取得します。次に例を示します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceCard-{cardFriendlyId}", string.Empty, "DeletePriceCard", string.Empty);
    EntityView view = Proxy.GetValue(query);
  2. ビューのプロパティを変更して、削除するプライス カードのフレンドリ ID を指定します。

    view.ItemId = $"Entity-PriceCard-{cardFriendlyId}";
  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

スナップショットは、指定された日時にプライス カードに適用できる価格を定義します。Pricing Views and Actions API は、スナップショットの addeditremoveadd tagremove tag アクションを提供します。

スナップショットの追加 (C#)

Pricing Views and Actions API を使用して、既存のプライス カードにスナップショットを追加できます。

プライス カードにスナップショットを追加するには:

  1. アクションのエンティティ ビューを取得します。次に例を示します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceCard-{cardFriendlyId}", "Details", "EditPriceCard", string.Empty);
    EntityView view = Proxy.GetValue(query);
  2. 必要に応じてビューのプロパティを変更します。次に例を示します。

    var displayNameProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("DisplayName"));
    displayNameProperty.Value = "Edited Card Display Name";
    var descriptionProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Description"));
    descriptionProperty.Value = "Edited Card Description";
  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

プライス カードのスナップショットのプロパティは、プライス カードのステータスが draft の場合に変更できます。

スナップショットを編集するには:

  1. アクションのエンティティ ビューを取得します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceCard-{cardFriendlyId}", "PriceSnapshotDetails", "EditPriceSnapshot", snapshotId);
    EntityView view = Proxy.GetValue(query);
  2. 必要に応じてプロパティのビューを変更します。

    var dateProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("BeginDate"));
    dateProperty.Value = DateTimeOffset.UtcNow.AddDays(5).ToString(CultureInfo.InvariantCulture);
    var tagsProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("IncludedTags"));
    tagsProperty.Value = "['Tag1', 'Tag2']";
  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

プライス スナップショットの削除 (C#)

Pricing Actions and View API を使用して、プログラムでプライス カードからプライス スナップショットを削除できます。

スナップショットを削除するには:

  1. アクションのエンティティ ビューを取得します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceCard-{cardFriendlyId}", string.Empty, "DeletePriceCard", snapshotId);
    EntityView view = Proxy.GetValue(query);
  2. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

Pricing Views and Actions API を使用して、階層型価格設定を適用できます。これは、購入した販売可能アイテムの数量に基づいて割引を適用する方法です。たとえば、階層型価格設定を使用すると、販売可能アイテムの価格を $5.00 に設定できますが、顧客が同じ販売可能アイテムを 5 つ以上購入した場合は、価格を $4.00 に下げることができます。

Pricing Views and Actions API は、プライス スナップショットに対する価格階層の追加、編集、および削除を行うメソッドを提供します。これらの操作は、ステータスが draft のプライス スナップショットでのみ実行できます。

スナップショットへの価格階層の追加 (C#)

スナップショットに複数の価格階層を同時に追加できます。価格階層を追加するときは、最初に通貨を選択してから、階層の数量と価格を指定する必要があります。

次の例は、数量 1 と 2、価格 20 と 10 を使用して、米ドル通貨で 2 つの階層を追加する方法を示しています。返されるのは 1 つの階層の子ビューのみです。複数の層を追加したい場合は、さらに子ビューを追加できます。

  1. アクションのビューを取得し、通貨をたとえば USD に指定します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceCard-{cardFriendlyId}", "PriceRow", "SelectCurrency", snapshotId);
    EntityView view = Proxy.GetValue(query);
    var currencyProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Currency"));
    var availableCurrenciesPolicy = currencyProperty.Policies.OfType<AvailableSelectionsPolicy>().FirstOrDefault();
    currencyProperty.Value = availableCurrenciesPolicy?.List.FirstOrDefault().Name;
    // == "USD"
    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

    注記

    応答は、1 つの価格階層の子ビューのみを返します。

  2. たとえば、ビューのプロパティを設定して、数量と価格を指定します。

    注記

    次の例に示すように、"PriceCell" エンティティを追加して、必要なプロパティ値を設定することで、複数の価格階層を追加できます。

    view = command.Models.OfType<EntityView>().FirstOrDefault(v => v.Name.Equals(view.Name));
    EntityView firstPriceCellView = view.ChildViews.OfType<EntityView>().FirstOrDefault(cv => cv.Name.Equals("PriceCell"));
    firstPriceCellView.Properties.FirstOrDefault(p => p.Name.Equals("Quantity")).Value = "1";
    firstPriceCellView.Properties.FirstOrDefault(p => p.Name.Equals("Price")).Value = "20";
    // only one PriceCell child view is returned, if you wish to add more than one tier you can add more PriceCell child views
    EntityView secondPriceCellView = new EntityView { Name = "PriceCell", EntityId = $"Entity-PriceCard-{cardFriendlyId}", ItemId = snapshotId };
    secondPriceCellView.Properties.Add(new ViewProperty { Name = "Quantity", Value = "2" });
    secondPriceCellView.Properties.Add(new ViewProperty { Name = "Price", Value = "10" });
    view.ChildViews.Add(cellView);
  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

価格階層の編集

スナップショットで価格階層の金額を変更できます。スナップショット内の複数の価格階層の価格を同時に編集できます。価格階層の通貨を変更することはできません。

価格階層の金額を変更するには:

  1. アクションのエンティティ ビューを取得します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceCard-{cardFriendlyId}", "PriceRow", "EditCurrency", $"{snapshotId}|USD");
    EntityView view = Proxy.GetValue(query);

    注記

    スナップショットに複数の価格階層が含まれている場合、応答は各階層を子ビューとして返します。

  2. PriceCellView プロパティの値を変更して、必要な金額を指定します。次に例を示します。

    EntityView firstPriceCellView = view.ChildViews.OfType<EntityView>().FirstOrDefault(cv => cv.Name.Equals("PriceCell"));
    firstPriceCellView.Properties.FirstOrDefault(p => p.Name.Equals("Price")).Value = "50";
    EntityView secondPriceCellView = view.ChildViews.OfType<EntityView>().LastOrDefault(cv => cv.Name.Equals("PriceCell"));
    secondPriceCellView.Properties.FirstOrDefault(p => p.Name.Equals("Price")).Value = "100";
  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

価格階層の削除

スナップショットから価格階層を削除したり、1 つのクエリで (同じ通貨の) 複数の価格階層を削除したりできます。

価格階層を削除するには:

  1. たとえば、米ドル通貨を使用した価格階層のアクションのエンティティ ビューを取得します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceCard-{cardFriendlyId}", "PriceRow",  string.Empty, $"{snapshotId}|USD");
    EntityView view = Proxy.GetValue(query);
  2. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

プライス スナップショットは、承認プロセスの対象となります。適用するには、プライス スナップショットが承認済みステータスである必要があります。スナップショット承認プロセス中、プライス スナップショットは次のように移行します。

  • Draft ステータスから ReadyForApproval ステータス

  • ReadyForApproval から Draft

  • ReadyForApproval から Approved

注記

承認されたスナップショットのステータスを変更することはできません。

スナップショットのステータスの draft から ReadyForApproval への変更 (C#)

ドラフト スナップショットのステータスを ReadyForApproval に変更して、承認を要求します。

スナップショットの承認を要求するには:

  1. アクションのエンティティ ビューを取得します。次に例を示します。

    {cardFriendlyId}", "SetSnapshotApprovalStatus", "RequestSnapshotApproval", snapshotId);
    EntityView view = Proxy.GetValue(query);
    
  2. ビューのプロパティを設定します。

    var commentProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Comment"));
    commentProperty.Value = "Requesting approval";
  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

スナップショットのステータスの ReadyForApproval から draft への変更 (C#)

承認のために送信されたスナップショットを却下するには、スナップショットのステータスを ReadyforApproval から draft に変更します。その後、ドラフト スナップショットを変更できます。

スナップショットを却下するには:

  1. アクションのエンティティ ビューを取得します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceCard-{cardFriendlyId}", "SetSnapshotApprovalStatus", "RejectSnapshot", snapshotId);
    EntityView view = Proxy.GetValue(query);
  2. ビューのプロパティを設定します。次に例を示します。

    var commentProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Comment"));
    commentProperty.Value = "Rejecting approval"
  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

スナップショットのステータスの ReadyForApproval から Approved への変更 (C#)

プライス スナップショットのステータスを ReadyforApproval から Approved に変更して、プライス スナップショットを承認します。承認されたスナップショットは変更できません。

プライス スナップショットを承認するには:

  1. アクションのエンティティ ビューを取得します。次に例を示します。

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-PriceCard-{cardFriendlyId}", "SetSnapshotApprovalStatus", "ApproveSnapshot", snapshotId);
    EntityView view = Proxy.GetValue(query);
  2. ビューのプロパティを設定します。次に例を示します。

    var commentProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Comment"));
    commentProperty.Value = "Approving";
  3. アクションを実行します。

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));