OCAPI 設定 23.1
OCAPI 設定を使用して、OCAPI クライアント許可や OCAPI キャッシングの制御といったさまざまな機能を管理します。
OCAPI 設定は Business Manager で構成します。OCAPI 設定を指定するには、このトピックで後述する形式に従った JSON ドキュメントを編集します。
OCAPI 設定を構成するには、次の手順を実行します:
- Business Manager で、管理 > サイトの開発 > Open Commerce API 設定の順に移動します。
- タイプの選択フィールドで、構成の API タイプを選択します。
- 範囲の選択フィールドで、構成の範囲を選択します。組織内のすべてのサイトに構成を適用するにはグローバルを、該当するサイトのみに適用するにはそのサイト名を使用します。
- テキストフィールドで、JSON ドキュメントを編集します。
- Save (保存) をクリックします。
特定のサイトでグローバル設定を上書きできます。設定は有効になるまで最大 3 分間キャッシュされます。
クライアントの設定と許可は、1 つのサイト (サイト固有) またはすべてのサイト (グローバル) に対して定義できます。サイトごとにクライアント ID のグローバル設定を上書きできます。
ほとんどの Data API リソースは組織固有のため、グローバルクライアント許可のみをサポートします。
OCAPI を使用するには、まず最初に、クライアントの許可を構成する必要があります。この許可によって、特定のリソースの読み取りや書き込みアクセスを制御します。デフォルトでは、いずれの許可も付与されません。OCAPI は、適切な許可をもたないクライアントアプリケーションリクエストを拒否し、401 HTTP ステータス (Unauthorized) を返します。
次の例は、JSON ドキュメントの形式を示します。
"_v" プロパティは、構成ファイルの構造のバージョンを示します。これは OCAPI バージョンと無関係であるため、すべての OCAPI バージョンのリソースの構成が許可されます。
このドキュメントを使用して、1 つのサイト内の複数のクライアントアプリケーションに対する Open Commerce API 許可を構成します。
| プロパティ | タイプ | 制約 | 説明 |
|---|---|---|---|
_v | String | 該当なし | Open Commerce API HTTP メソッドフィルター。JSON プロパティが追加された場合や、プロパティの動作が変更された場合は、新しいバージョンが作成されます。可能な限り、最新の構成ファイルの構造バージョンを使用してください。 |
clients | [Client] | 該当なし | クライアント固有の許可のドキュメントの配列。 |
このドキュメントを使用して、クライアントアプリケーションの Open Commerce API 許可を表示します。
| プロパティ | タイプ | 制約 | 説明 |
|---|---|---|---|
allowed_origins | [String] | 該当なし | CORS リクエストで使用された許可されているオリジンの配列。 |
client_id | String | mandatory=true, nullable=false | クライアントアプリケーション ID。 |
response_headers | Map<String,String> | 該当なし | カスタムレスポンスヘッダーの名前と値のペアのマップ。サポートされているヘッダーは 'P3P' で、カスタムヘッダーは 'X-' で始まります。'X-DW' で始まるカスタム Commerce Cloud Digital ヘッダーは許可されていません。 |
resources | [Resource] | 該当なし | リソース固有の許可のドキュメントの配列。 |
このドキュメントを使用して、リソース固有の許可と設定を構成します。
| プロパティ | タイプ | 制約 | 説明 |
|---|---|---|---|
cache_time | Integer | 該当なし | レスポンドドキュメントが古くなるまでの期間 (秒単位)。最小キャッシュ時間は 0 秒、最大は 86,400 秒 (24 時間) です。値が指定されていない場合、デフォルトは 60 秒です。詳細については、キャッシングを参照してください。 |
config | Map<String,String> | 該当なし | 特殊なレスポンスドキュメントのプロパティに対して返す値を決定するマップ。予約されたキー/値のペアを構成することによってこのマップを制御します。詳細については、カスタマイズを参照してください。 |
methods | [String] | mandatory=true, nullable=false | Open Commerce API HTTP メソッドフィルター。たとえば、フィルター ["get","patch"] は、指定されたリソースパスの GET と PATCH メソッドへのアクセスを許可します。リソースでサポートされているメソッドを指定できます。次のメタデータ呼び出しを使用して、Shop API、バージョン 23.1 で使用可能なすべてのリソースとメソッドをリストできます: http://{your-domain}/dw/meta/rest/shop/v23_1?client_id={your-client-id} |
personalized_caching_enabled | Boolean | 該当なし | キャッシュ可能な Shop API リソースのパーソナル化されたキャッシング動作を決定するフラグ。デフォルトでは、顧客コンテキスト (JWT) が指定された場合に、システムはパーソナライズされたリソースをキャッシュします。このプロパティを使用して、パーソナライズされたキャッシュ (たとえばパフォーマンスの向上など) を明示的に無効にすることができます。レスポンスがどの顧客の場合でも必ず同じである場合、そしてその他のパーソナライズロジック (たとえばフックでなど) が適用されない場合にのみ、パーソナライズされたキャッシュを無効にします。 |
read_attributes | String | 該当なし | レスポンスドキュメントに含めるプロパティを制御する文字列。構成値はプロパティ選択の構文を使用して指定する必要があります。 |
resource_id | String | mandatory=true, nullable=false | OCAPI リソース識別子。たとえば、/products/*/images や /products/specific_id/images などです。このプロパティでは、リソース ID を記述するための Ant パススタイルがサポートされています。ワイルドカードまたは特定の商品 ID を指定できます。また、パターン /products/** を指定して、使用可能なすべてのサブリソースにアクセスすることもできます。次のメタデータ呼び出しを使用して、Shop API、バージョン 23.1 のすべてのリソース ID をリストできます: http://{your-domain}/dw/meta/rest/shop/v23_1?client_id={your-client-id} |
version_range | [VersionRange] | 該当なし | OCAPI バージョンのサブセットにのみ許可を付与する VersionRange ドキュメントの配列。 |
write_attributes | String | 該当なし | S リクエストドキュメントに含めるプロパティを制御する文字列。構成値はプロパティ選択の構文を使用して指定する必要があります。 |
このドキュメントを使用して、Open Commerce API バージョンのサブセットにのみリソース許可を付与します。範囲を定義するには、プロパティ from および until を使用します。少なくともどちらかのプロパティを指定する必要があります。
| プロパティ | タイプ | 制約 | 説明 |
|---|---|---|---|
from | String | 該当なし | 開始バージョン (たとえば、23.1)。from バージョンを指定しない場合は、until バージョンより前のすべてのバージョンにアクセスできます。 |
until | String | 該当なし | 終了バージョン (たとえば、23.1)。until バージョンは 範囲 に含められません。(たとえば、until バージョンが 19.3 の場合、含まれる最新のバージョンは 19.1 です。) until バージョンを指定しない場合は、最新バージョンを含むすべてのバージョンにアクセスできます。 |
展開手法をサポートするリソースは、他のリソースと同様に処理されます。このため、商品画像情報へのアクセスを制限したい場合、各リソースに個別のクライアント許可を構成します (商品の基本リソースを /products/*、および画像のサブリソースを /products/*/images など)。
Open Commerce API では、データを返す方法をカスタマイズできます。次のリソースのプロパティを設定できます:
/product_search/images(Shop API)/products/*/availability(Shop API)/products/*/prices(Shop API)/search_suggestion(Shop API)
/product_search/images (Shop API)
特定の画像プロパティに画像表示タイプを構成して、どのように画像情報が返されるかをカスタマイズできます。このリソースには、次の 3 つのキー/値のペアが予約されています:
- "
search_result.hits.image:view_type":"detail" "search_result.variation_attributes.values.image:view_type":"thumbnail""search_result.variation_attributes.values.image_swatch:view_type":"swatch"
これらのプロパティは、実際の画像表示タイプを定義します。表示タイプに基づいて、Shop API が希望する画像情報を返します。view_type が設定されていない、または view_type が不明の場合、画像プロパティはレスポンスの一部にはなりません。例:
/products/*/availability (Shop API)
(Shop API によって返される) 最大しきい値を構成して、実際の ATS (販売可能数量) と在庫レベルを非表示にできます。このリソースには、次の 2 つのキー/値のペアが予約されています:
- "
product.inventory.ats.max_threshold":"100" "product.inventory.stock_level.max_threshold":"50"
ATS (販売可能数量) と在庫レベルはマーチャントにとって機密情報です。これらのプロパティが設定されていない場合は、API レスポンスプロパティはデフォルト値 999999 になります。
/products/*/prices (Shop API)
product.prices プロパティで、表示する価格表の価格を構成できます。このリソースには、次の 1 つのキー/値のペアが予約されています:
- "
product.prices.price_book_ids":"usd-list-prices,usd-sale-prices"
価格表が定義されていない場合は、プロパティはレスポンスの一部にはなりません。
/search_suggestion (Shop API)
特定の画像プロパティに画像表示タイプを構成して、どのように画像情報が返されるかをカスタマイズできます。このリソースには、次の 3 つのキー/値のペアが予約されています:
- "
suggestion.product.image:view_type":"small"
これらのプロパティは、実際の画像表示タイプを定義します。表示タイプに基づいて、Shop API が希望する画像情報を返します。view_type が設定されていない、または view_type が不明の場合、画像プロパティはレスポンスの一部にはなりません。例: