j1.5.1
API の概要
買い物客がキーワードと絞り込みを使用して商品を検索できる検索機能には、Shopper Search API を使用します。検索結果は、API で選択したエンドポイントに応じて、商品または提案になります。
Shopper Search API ではキャッシュが提供されます。詳細については、サーバー側の Web 階層キャッシングを参照してください。
認証と認可
API をリクエストするクライアントには、商品検索および検索の提案リソースへのアクセス権が必要です。
Shopper Search API では、Shopper Customers エンドポイントを介して取得した JWT が必要です。
https://{shortCode}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/{organizationId}/customers/actions/login
ユースケース
検索の提案の提供
買い物客が検索している間に検索の提案を提供するには、Shopper Search API を使用します。
たとえば、Salesforce Commerce API を使用してショッピングアプリケーションを構築しているデベロッパーが、商品、ブランド、カテゴリの提案を提供したいとします。買い物客が、定義可能な最小文字数を超える検索フレーズを入力して GET Search Suggestion エンドポイントがリクエストされると、プラットフォームは、商品 (名前、ID)、ブランド (名前)、カテゴリ (名前、ID) を含む提案のセットを返します。買い物客は、提示された補完候補や修正候補を使用することで、目的の検索結果によりすばやくたどり着くことができます。
検索結果の提供
買い物客の検索クエリに対する商品結果を取得するには、Shopper Search API を使用します。
たとえば、Salesforce Commerce API を使用してショッピングアプリケーションを構築しているデベロッパーが、商品検索機能を実装したいとします。買い物客が検索フレーズを入力して GET Product Search エンドポイントがリクエストされると、プラットフォームはキーワード検索を実行し、並べ替えられた検索結果を返します。並べ替えられた検索結果は、指定された値 (たとえば、価格帯) に従って絞り込むことができます。 商品検索結果には、定義可能な数の商品検索ヒットが含まれます。商品検索ヒットは、一致した商品をその ID と名前とともに示します。さらに、検索ヒットには、商品画像、価格、代表商品、バリエーションが含まれます。検索ヒットに加えて、検索結果には絞り込みオプションと並べ替えオプションも含まれます。
プロモーション情報の取得
注: これは、クエリパラメーターで promotions が指定されている場合にのみ適用されます。
プロモーションは、買い物客が特定の購入要件を満たしたときに割引を提供します。
プロモーション情報についてはプロモーション詳細で詳しく説明されていますが、以下にいくつかの重要なポイントを示します。
- 買い物カゴプロモーションおよび配送プロモーションの価格割引は、'getProduct' エンドポイントまたは 'getProducts' エンドポイントでは決して返されません。
- プロモーション価格は、無条件プロモーションに含まれる商品に対してのみ返されます。
- コールアウトメッセージは、'getProduct' エンドポイントおよび 'getProducts' エンドポイントで常に返されます。
デフォルトでは、'getProduct' と 'getProducts' は、クエリされた商品に対するプロモーション情報を返します。プロモーション情報には、価格情報とコールアウトメッセージ情報の両方が含まれます。ただし、取得される具体的な価格情報およびコールアウト情報は、次の要素によって決まります。
- プロモーションタイプ
- 商品タイプ
- 商品の購入要件
一部のプロモーションは Product Data Page (PDP) または Product Listing Page (PLP) に表示できますが、他のプロモーションは、注文レベルのプロモーション「価格情報を表示するには商品を買い物カゴに追加してください」のように、買い物カゴのコンテキストで表示されます。SCAPI 上に PDP または PLP を設計する際には、設計が実装可能な機能と一致するように、レスポンスに何が含まれるかを理解しておくことが重要です。
注: バリアント商品を検索すると、Product Search API はマスター商品を主要な検索ヒットとして返します。プロモーションデータ (productPromotion) がが返される場合、返される商品はマスター商品であるため、価格情報は含まれません。価格情報を取得するには、promotions expand パラメーターとともにクエリ文字列 allVariationProperties=true を渡します。これにより、プロモーションが無条件である場合に、バリアント商品の価格データが返されます。allVariationProperties フラグは、結果に含めるバリエーションプロパティを指定します。
プロモーションの役割による商品のフィルタリング
pmid (プロモーション ID) とpmpt (プロモーション商品タイプ) の絞り込みパラメーターを組み合わせて使用することで、プロモーション内での役割に基づいて商品をフィルタリングできます。これにより、プロモーション内の特定タイプの商品を見つけることができます。
pmid: フィルタリング対象のプロモーション ID を指定します。pmpt: そのプロモーション内で返す商品のタイプを指定します。all: プロモーションに関連するすべての商品を返します (デフォルトの動作)。qualifying: プロモーションの適用条件を満たすが、割引やボーナスは受け取らない商品のみを返します。discounted: プロモーションで割引を受ける商品のみを返します。bonus: ボーナスとして付与される商品のみを返します。
使用例:
GET /organizations/{organizationId}/product-search?refine=pmid=summer-sale&refine=pmpt=discounted
この例では、"summer-sale" プロモーションで割引を受ける商品のみが返されます。
**注: **pmpt パラメーターは、pmid と組み合わせて使用した場合にのみ効果があります。pmid を指定せずに pmpt を指定した場合、これは無視され、すべての商品が返されます。
買い物客のパーソナライズ
SCAPI レスポンスは、Shopper Context API またはフックを使用してパーソナライズできます。Shopper Context API で特定の値を設定することで、買い物客のコンテキストに基づいて 'getProduct' エンドポイントまたは 'getProducts' エンドポイントのレスポンスを変更できます。たとえば、モバイルデバイスを使用している買い物客に対して、5% の割引や送料無料を提供できます。
JWA キャッシュ
レスポンスは JWA でキャッシュされます。つまり、レスポンスに含まれるプロモーションデータも、Business Manager の機能スイッチの構成で指定された TTL (Time to Live) に基づいてキャッシュされます。 買い物客コンテキストの値が更新されると、その更新された買い物客コンテキストが商品プロモーションデータの取得に影響するかどうかを確認するためのチェックが実行されます。影響する場合、レスポンスはソースから取得され、JWA にキャッシュされます。
詳細については、サーバー側の Web 階層キャッシングを参照してください。
フックの使用
フックの使用方法の詳細については、フックによる拡張性を参照してください。
ベストプラクティス
これらのベストプラクティスは、B2C Commerce 24.3 で一般提供されている機能を対象としています。
パフォーマンスを向上させるために、GET Product Search エンドポイントを呼び出す際は、次のことを推奨します。
selectクエリパラメーターを使用して、指定したフィールドまたはフィールドセットのレスポンスをフィルタリングし、不要なデフォルト出力を除外します。たとえば、関連する商品名、ID、バリアント、およびそのバリアントの商品 ID のみを返すようにレスポンスをフィルタリングします。- 商品一覧ページ (PLP) に情報を表示するために、GET Product Search エンドポイントと GET Products エンドポイントの両方を呼び出すのではなく、GET Product Search エンドポイントへの API リクエストに限定します。商品タイルのレンダリングに必要な追加の商品情報を提供するには、次の機能を使用します。
- 許容値:
expandクエリパラメーターのpromotions値 - クエリパラメーター:
perPricebook、allImages、allVariationProperties - レスポンス:
productPromotions、imageGroups、priceRanges、tieredPrices、variants、variationGroups
- 許容値:
- PLP の要件を満たすために必要と考えられる
expand値とクエリパラメーターのみを渡します。大量の情報をリクエストすると、特に返されるデータが多い場合 (たとえば、多数の imageGroups や variants) に、レイテンシーが増加する可能性があります。
Let us know so we can improve!