OCAPI ベストプラクティス 23.1

ここに記載されているヒントは、拡張可能で高パフォーマンスの OCAPI アプリケーションを開発する上で役立ちます。

OCAPI リクエストとストアフロントリクエスト (コントローラーまたはパイプライン) では、異なるリソースコストとプラットフォームのオーバーヘッドが発生します。ここに記載されている情報は、お使いのアプリケーションにとって最適な選択を行う上で役立ちます。

  • 主要な違いは?

    • :
      • OCAPI リクエストには独自のアプリケーション層のキャッシュがあります。これは Web 層のキャッシュのクリア動作に似ていますが、Web 層は OCAPI リクエストをキャッシュしません。
      • Web 層は OCAPI リクエストをキャッシュしないため、OCAPI リクエストではキャッシュステータスに関係なく、キャッシュされていないストアフロントリクエストと同じアプリケーション層のオーバーヘッドが常に生じます。このため、OCAPI リクエストでは、Web 層によってキャッシュされるストアフロントリクエストよりも高いリソースコストが発生します。
      • 複数のレスポンスドキュメントを取得する OCAPI リクエストでは、そのドキュメントの中で最小のキャッシュ TTL がすべてのドキュメントに適用されます。一方、ストアフロントリクエストでは、リモートインクルードコンテンツの各要素の個別のキャッシュ TTL が優先されます。

  • スレッド動作への影響は?

    • :スレッド動作は、OCAPI リクエストとストアフロントリクエストで同じです。各リクエストで、レスポンスを処理するための新しいスレッドが生成されます。適切なリクエストのペイロードサイズは状況に応じて異なる場合があります。

      • 長時間実行されるリクエストでは、スレッドが使用中のままになることに注意してください。
      • ペイロードサイズとリクエスト時間の適切なバランスを判断するには、お使いのアプリケーションのパフォーマンスをモニターし、必要に応じて微調整します。このバランスは、各アプリケーションに特有です。たとえば、1 回のリクエストで 50 のレスポンスを返す必要がある場合もあれば、10 回のリクエストで各 5 つのレスポンスを返す方が、より優れたパフォーマンスを提供する場合もあります。
      • バッチリクエストを適切に使用します。

  • OCAPI パフォーマンスの低下が顧客体験に与える影響は?

    • リクエスト、ストアフロントリクエスト、およびスケジュール済みジョブはすべて、プラットフォームのリソースプールを共有します。このため、あるエリアでのパフォーマンスの低下によって、顧客体験に待ち時間が発生するだけでなく、他のエリアでのパフォーマンスにも影響が生じます。

ここでは、OCAPI リクエストのキャッシングに関する考慮事項をさらに詳しく説明します。

キャッシュ可能な OCAPI リクエストのタイプは?

  • Data API: いいえ
  • Meta API: 可
  • Shop API: 可 (ほとんどのリクエスト)

各 Data API リクエストではリアルタイムのアプリケーション層のオーバーヘッドが生じます。お使いのアプリケーションで呼び出す Data API の数を最小限に抑えるようにしてください。

  • Meta API リクエストはどのようにキャッシュされますか?

    • API リソースは常に 1 日間キャッシュされます。この TTL は構成できません。Meta API インスタンスキャッシュをクリアするには、Business Manager ページキャッシュ全体を無効にします。(キャッシュパーティションのみを無効にしても、Meta API キャッシュはクリアされません。)

ページキャッシュをクリアすると、アプリケーションサーバーに大きな負荷がかかります。ページキャッシュの手動によるクリアは必要な場合にのみ行い、トラフィックの多い時間帯は避けるようにします。

  • Shop API リクエストはどのようにキャッシュされますか?

    • :2 つのプロパティを使用して、個々の Shop リソースのキャッシングを OCAPI 設定で構成します。適切な TTL を構成してキャッシュミス数を最小限に抑え、優れたリクエスト URL 戦略を用いてキャッシュストア (重複するキャッシュコンテンツ) を削除します。

      • cache_time (Integer): キャッシュされたレスポンスドキュメントの有効期間 (秒単位)。デフォルト値は 60、有効な範囲は 0 から 86,400 (24 時間) です。
      • personalized_caching_enabled (Boolean): 顧客コンテキスト (JWT) ごとにレスポンスドキュメントをキャッシュするかどうかを指定します。デフォルト値は true です。パーソナル化されたキャッシングを無効にするとパフォーマンスが向上しますが、これはレスポンスドキュメントがあらゆる顧客に対応でき、かつ顧客固有の処理を必要としない場合に限り実行できます。

  • Shop API レスポンスに対してキャッシュキーはどのように生成されますか?

    • キャッシュキーはストアフロントページのキャッシュキーに似ています。これらは次のリクエスト要素から生成されます。

      • hostname
      • siteId
      • clientId
      • 展開パラメーター
      • カスタムリクエスト URL パラメーター

  • リクエスト URL がキャッシュパフォーマンスに与える影響は?

    • :リクエスト URL の構造は、生成されるキャッシュキーに影響を与えます。一致するリクエストが同じパラメーターを含んでいても、それらのパラメーターが異なる順序で結合されている場合は、複数のキャッシュエントリが生成されます。たとえば、次の 3 つのリクエストでは、同じレスポンスデータに対して 3 つの異なるキャッシュエントリが発生します:

      • dw/shop/v18_8/products/123?client_id=[your_own_client_id]&expand=availability,variations
      • dw/shop/v18_8/products/123?expand=availability,variations&client_id=[your_own_client_id]
      • dw/shop/v18_8/products/123?expand=variations,availability&client_id=[your_own_client_id]

      重複するエントリによってキャッシュパフォーマンスが著しく低下する場合があります。これを防ぐために、リクエスト URL を構築する場合は常に、クエリパラメーターとパラメーター値をアルファベット順に結合します。

  • キャッシュに存在する OCAPI データのタイプは?

    • データは、個々のドキュメントエントリと、複数のドキュメントを結合する複合エントリ (オブジェクトドキュメントと、リクエストに含まれる展開を表すドキュメント) の 2 つの方法でキャッシュされます。

      • 個々のドキュメントは、別々にキャッシュに保存され、また別々にキャッシュから取得されます。たとえば、複数の Product ドキュメントを返すリクエストは、展開が含まれていないと、一致する個々の Product ドキュメントのキャッシュをチェックします。
      • 展開ドキュメントを含む複合データは、リクエストされたドキュメントの組み合わせに一致するエントリが存在する場合に限り、キャッシュから取得されます。 (リクエストされた展開はキャッシュキーに含まれることに注意してください。) 一致するエントリが存在しない場合は、リクエストされたドキュメントはすべてデータベースから取得され、1 つの複合キャッシュエントリとして一緒に保存されます。一方このキャッシュエントリは、同じドキュメントの組み合わせのリクエストに対してのみ利用可能です。たとえば、Product ドキュメントに加えて、Inventory ドキュメントと Promotion ドキュメントの展開を返すリクエストがあるとします。この場合、一致する Product、Inventory、Promotion の各ドキュメントを含む結合エントリが見つかった場合に限り、データが取得されます。このようなエントリは一致するリクエストに対してのみ利用可能なため、展開を含まない Product ドキュメントのみのリクエストでは、このエントリは無視されます。

複合エントリがキャッシュに保存されると、このエントリの TTL は、含まれているドキュメントタイプの中で最も短く構成された TTL と等しくなります。この動作は、ストアフロントパイプラインとページキャッシングの動作 (異なるページ要素が別々にキャッシュされる場合がある) とは異なります。たとえば、TTL が 86,400 秒の Product ドキュメントと、TTL が 300 秒の Inventory ドキュメントがあるとします。availability (入手可能性) 展開 (この場合、Inventory ドキュメントが返されます) を含む Product ドキュメントのリクエストでは、TTL が 300 秒のキャッシュエントリが生成されます。このため、キャッシュ時間が類似するドキュメントをまとめたリクエストを可能な限り使用します。また、計画を立てる際は、予想される回数よりも頻繁にデータベースからデータを取得するリクエストに注意してください。

  • キャッシュエントリはリクエストとレスポンスのどちらに基づいていますか?

    • :キャッシュエントリはリクエストではなくレスポンスに基づいています。このため、すべての OCAPI リクエストで、これを解析し、キャッシュまたはデータベースからドキュメントを取得するためにアプリケーション層のオーバヘッドが生じます。

  • レプリケーションが OCAPI キャッシングに与える影響は?

    • :レプリケーションを実行すると、すべての OCAPI キャッシュとサイトキャッシュがクリアされます。

  • OCAPI キャッシュのクリア方法は?

    • キャッシュをクリアするには、サイトのページキャッシュを無効にします。こうすることで、両方のキャッシュが無効になります (これらは別々にクリアできません)。ページキャッシュパーティションの無効化を参照してください。

ページキャッシュをクリアすると、アプリケーションサーバーに大きな負荷がかかります。ページキャッシュの手動によるクリアは必要な場合にのみ行い、トラフィックの多い時間帯は避けるようにします。
OCAPI キャッシュのパフォーマンスをモニタリングできるツールはありますか?

ラットフォームでは、OCAPI キャッシュを直接表示することはできません。Business Manager のレポートとダッシュボードでは、ストアフロントパイプラインリクエストについてのみ、キャッシュ動作を確認できます。

一部の Shop API の GET と HEAD リクエストのレスポンスには、取得されたドキュメントに構成されているキャッシュ時間を反映する Cache-Control ヘッダーが含まれています。このヘッダーのデータを使用して、データを保持し、OCAPI リクエストのタイミングを適切に計ることで、B2C Commerce プラットフォーム外のドキュメントを効率的にキャッシュできます。ヘッダーの max-age 引数は、返されたドキュメントを次回取得するまでの使用時間を指定します。

OCAPI レスポンスデータをキャッシュするために、Cache-Control ヘッダーの max-age 引数をどのように使用できますか?

max-age 引数は、OCAPI キャッシュのデータの残りの TTL を表します。たとえば、cache-time が 900 秒に構成されているリソースがあるとします。

  • そのリソースに対して作成した GET リクエストを使用して、まだキャッシュされていないドキュメントを取得します。レスポンスヘッダーに 900 の max-age 値が含まれます。ドキュメントがキャッシュに保存されます。
  • 別の GET リクエストを使用して、120 秒後に同じドキュメントを取得します。レスポンスヘッダーに 780 の max-age 値が含まれます。この値は、構成されているリソースのキャッシュ時間 (900) からドキュメントの現在のキャッシュ内の時間 (120) を差し引くことで算出されています。お使いのアプリケーションでドキュメントを再度取得しなくても、780 秒の有効な TTL が経過するまでこのデータを使用できます。
どの Shop API リソースに Cache-Control ヘッダーが含まれていますか?

のリソースで、GET と HEAD のリクエストのレスポンスに Cache-Control ヘッダーが含まれています。

  • カテゴリ
  • Content
  • ContentSearch
  • CustomObjects
  • Folders
  • Products
  • ProductSearch
  • Promotions
  • SearchSuggestion
  • Site
  • 店舗

機密データ (顧客または注文処理データなど) に関連付けられているため、次のリソースには Cache-Control ヘッダーが含まれていません。

  • Ai
  • Baskets
  • Customers
  • GiftCertificate
  • OrderSearch
  • Orders
  • PriceAdjustmentLimits
  • ProductLists
  • Sessions
外部のコンテンツ配信ネットワーク (CDN) を使用して OCAPI パフォーマンスを向上できますか?

部 CDN を使用してコンテンツを管理する場合は、OCAPI リクエストを仲介し、Cache-Control ヘッダーに基づいて外部キャッシングを管理するように、外部 CDN を構成できます。

  • 一部の OCAPI レスポンスを静的コンテンツとして扱い、デフォルトの最小キャッシュ時間を提供できます。
  • CDN の機能に応じて、複数のキャッシュパーティションを作成し、特定の OCAPI リクエストを特定のパーティションと関連付けることができます。その後、そのリクエストのセットに適用するように、各パーティションのキャッシュ動作をカスタマイズできます。
  • 外部の OCAPI キャッシュをストアフロントページキャッシュとは別に効率的に分離して管理できます。
埋め込み B2C Commerce CDN を使用して OCAPI パフォーマンスを向上できますか?

いえ。埋め込み CDN には OCAPI リクエストを管理できるリバースプロキシは含まれていません。

以下に OCAPI パフォーマンスを最大限に高めるための一般的なヒントを紹介します。

  • カスタムフックを使用する際の留意事項は?

    • :
      • フックによって依存関係および必要以上のリクエストオーバーヘッドが生じます。メリットがコストを上回る場合にのみフックを使用します。
      • OCAPI レスポンスを変更する場合は、可能な限り Web オブジェクトを使用します。必要な場合のみ Script API を使用し、フックのビジネスロジックをシンプルに保ちます。
      • フック内での永続的オブジェクトのリクエストは避けます (ProductMgr.getProduct() や product.getVariations() など)。

  • キャッシュ時間の構成がカスタムフックに与える影響は?

    • リソースに添付されているカスタムフックのロジックは、データベースからデータが取得された場合にのみ実行されます。キャッシュからドキュメントを取得しても、カスタムフックはトリガーされません。

  • カスタムコントローラーを利用するカスタム API エンドポイントを作成する際の注意事項は?

    • :コントローラーはステートフルです。コントローラーエンドポイントにアクセスするたびに新しいリクエストオブジェクトが生成されます。新しいセッションが生成される可能性もあります。セッションの使用を続行するには、クライアントアプリケーションは最初のレスポンスに埋め込まれた Cookie を承諾し、その後のリクエストにその Cookie を含める必要があります。これを実行しないと、リクエストのたびに新しいセッションが作成され放棄されます。この結果、膨大な量の孤立したセッションが生じ、パフォーマンスに大きな影響を与える可能性があります。

  • ブラウザーやモバイルアプリなど、異なるクライアントから OCAPI リクエストを作成する際に好ましい方法とは?

    • :JSON Web Token (JWT) を取得し、このトークンを使用してリクエストを行います。こうすることで、プラットフォームリソースを節約し、他のメリットが生じます。

      • 各リクエストにセッションを作成する代わりに、セッションを再使用できます。
      • OCAPI リクエストに対して ORM キャッシュを有効にします。
      • パーソナライズされたキャッシュを有効にします。