ベース URL とリクエストの作成
B2C Commerce API の使用を開始する前に、ベース URL の構成とインスタンス固有のパラメーターについて理解しておく必要があります。
このガイドでは、B2C Commerce API へのリクエストを適切な書式で作成する方法と、必要なすべてのパラメーターについて説明します。URL に必要な特定の構成情報を特定するには、「構成値」セクションを参照してください。
B2C Commerce API へのすべてのリクエストのベース URL は、B2C Commerce インスタンスを識別し、リクエストを正しい API ファミリーに導くためのパターンに従っています。このパターンを理解するために、インスタンスと API ファミリーに応じて URL の部分にプレースホルダー (二重波括弧で囲まれている) を使用したベース URL を見ていきます。
Shopper Baskets (買い物客の買い物カゴ) で作業している場合を除き、v1 のバージョンを必ず指定してください。Shopper Baskets の場合は、必要に応じて v1 または v2 を指定します。
次に、プレースホルダーを以下の値の例で置き換えます。
| プレースホルダー | 値 |
|---|---|
{{shortCode}} | kv7kzm78 |
{{apiFamily}} | product |
{{apiName}} | shopper-products |
{{organizationId}} | f_ecom_zzte_053 |
値の例を使ったベース URL は次のようになります。
この例では、ショートコードと組織 ID はデモ Sandbox (サンドボックス) のものです。自社の B2C Commerce インスタンスでこれらの値を検索する方法については、次のセクションで説明します。
B2C Commerce インスタンスで B2C Commerce API を使用する場合、そのインスタンスに関連する一連の構成値を収集する必要があります。これらの構成値は、設定プロセスを完了し、API リクエストを作成するために必要です。
一般的な構成値のセットは次のようなものです。
| 構成値 | 例 |
|---|---|
| 組織 ID | f_ecom_zzte_053 |
| ショートコード | kv7kzm78 |
| サイト ID | RefArch |
このガイドでは、各構成値の詳細と、その値をどこで見つけることができるかについて説明します。
組織 ID は、B2C Commerce インスタンスを識別する短い文字列です。各インスタンスは、それぞれ専用の組織 ID (f_ecom_zzte_053 など) をもちます。
インスタンスの組織 ID は、Business Manager で調べることができます。この場合、Account Manager で Business Manager Administrator (管理者) の役割をもっていて、インスタンスの Business Manager URL を知っている必要があります。
Business Manager URL は次のようになります。
組織 ID を調べるには、次のようにします。
- インスタンスの Business Manager URL を開きます。
- Account Manager の認証情報を使用してログインします。
- 管理 > サイトの開発 > Salesforce Commerce API 設定の順に移動します。
組織 ID がページに表示されます。クリップボードにコピーをクリックし、後で参照しやすい場所にペーストしておきます。
組織 ID で、2 つ目の下線文字 (_) の間にある部分は、レルム ID と呼ばれる 4 文字の文字列です。組織 ID が f_ecom_zzte_053 の場合、レルム ID は zzte です。
レルムは、B2C Commerce インスタンスのセットを示し、これにはプライマリインスタンスとセカンダリインスタンスの両方が含まれます。レルムの詳細については、B2C Commerce ドキュメントの概念と用語を参照してください。
組織 ID で、3 つ目の下線文字 (_) の後にくる部分は、インスタンス ID と呼ばれる 3 文字の文字列です。組織 ID が f_ecom_zzte_053 の場合、インスタンス ID は 053 です。
インスタンス ID は、レルム内のインスタンスを認識するための 3 文字の文字列です。
- Production (本番)、Staging (ステージング)、Development (開発) の各インスタンスのインスタンス ID は、それぞれ
prd、stg、devです。 - On-Demand Sandbox (オンデマンドのサンドボックス) のインスタンス ID は 3 桁の数字で、Sandobox が作成されるのに応じて増えます。
- POD Sandbox の場合、インスタンス ID の書式は
sXXで、XXは 01 から 99 までの間の数字を指します。
B2C Commerce インスタンスは、Shopper Login and API Access Service (SLAS) などの補助システムに関連付けられている場合に、「テナント」と見なされます。インスタンスを SLAS などのシステムに関連付けるには、インスタンスをテナント ID で識別する必要があります。テナント ID は 4 文字のレルム ID で開始し、それに、下線 (_) とインスタンス ID が続きます。
Omnichannel Inventory (OCI) を更新する場合は、OCI からテナント ID を取得します。詳細は、「B2C Commerce 向け Salesforce Omnichannel Inventory 実装ガイド」を参照してください。
さまざまなタイプのインスタンスのテナント ID の例を以下に示します。
| インスタンスタイプ | レルム ID | インスタンス ID | テナント ID |
|---|---|---|---|
| Staging (ステージング) | bcgl | stg | bcgl_stg |
| On-Demand Sandbox (オンデマンドのサンドボックス) | zzte | 053 | zzte_053 |
| POD Sandbox (POD サンドボックス) | zzrf | s01 | zzrf_s01 |
ショートコードは、ルーティングの目的でレルムに割り当てられる 8 文字の文字列です。ショートコードはレルム全体に、すべてのインスタンスにまたがって適用されます。
ショートコードは組織 ID と同じ場所にあります。以下の方法で調べることができます。
- インスタンスの Business Manager URL を開きます。
- Account Manager の認証情報を使用してログインします。
- 管理 > サイトの開発 > Salesforce Commerce API 設定の順に移動します。
レルムで B2C Commerce API を使用したことがない場合は、ショートコードのリクエストをクリックしてリクエストします。
ショートコードが CDN および構成に含まれるすべてのルーティングシステムに読み込まれるまでに、最大で 24 時間かかることがあります。
ショートコードは api.commercecloud.salesforce.com と連結されて、API 呼び出しのための API ホスト名となります。たとえば、u8ak193h.api.commercecloud.salesforce.com となります。
サイト ID は、アクセスしたいデータが含まれるサイトの名前 (「チャネル」と呼ばれることもある) です。たとえば、RefArch や SiteGenesis などです。
Business Manager でサイトのリストを確認するには、次のようにします。
- インスタンスの Business Manager URL を開きます。
- Account Manager の認証情報を使用してログインします。
- 管理 > サイト > サイトの管理の順に移動します。
サイト名の詳細については、B2C Commerce ドキュメントの Create a Site in Business Manager (Business Manager でのサイトの作成) を参照してください。
Shopper Baskets (買い物客の買い物カゴ) には、必要に応じて v1 または v2 を指定します。
その他のすべての API では、v1 を指定します。
次に、ベース URL を getProduct エンドポイントと組み合わせて、RefArchGlobal サイトの商品 ID 25695327M の商品情報を取得しましょう。
エンドポイント名 getProduct は URL に含まれないことに注意してください。文字列 getProduct は、ドキュメント内でエンドポイントを識別するためにだけ使用されます。そのエンドポイントの URL は、products/{{productID}} をベース URL に追加することで作成できます。
このエンドポイントの例の完全な URL には、クエリ文字列に必要なクエリパラメーターである siteId も含まれます。
エンドポイントの多くには、必要なクエリパラメーターが含まれています。Shopper API の場合、siteId パラメーターがしばしば必要です。
有効なリクエストを行うには、適切に作成された URL だけでは不十分です。大部分のエンドポイントには、HTTP ヘッダーとリクエストボディのための追加の要件があります (通常は JSON オブジェクト)。API 参照資料 を常に確認して、各エンドポイントの正確な要件を調べてください。
B2C Commerce インスタンスのすべての構成値を収集したら、認可を参照して API アクセスのための API クライアントを設定します。この設定は、Shopper API と Admin API で異なります。
B2C Commerce API についてより詳細に学習するには、次のトピックを読むことをお勧めします。
他の Commerce API ユーザーから学ぶには、コミュニティガイドを参照してください。