OCAPI URL 構文 23.1
Open Commerce API は、URL に特殊なスキーマを使用します。各 URL は、ベース URL と拡張 URL から成り立っています。ベース URL はすべての API リクエストで同じです。一方、拡張 URL はリソースと操作に応じて異なります。Open Commerce API の機能にアクセスするには、次のように URL を作成します。
ベース URL は、Production (本番) インスタンスで使用するか、または Production (本番) インスタンス以外 (Staging (ステージング)、Development (開発)、および Sandbox (サンドボックス) を含む) で使用するかに応じて、構造が異なります。Production (本番) インスタンスでは、ベース URL は次の構造をもちます:
エイリアスの詳細については、ホスト名のエイリアスを参照してください。Production (本番) インスタンス以外では、ベース URL は次の構造をもちます:
{api_type} は shop、data、または meta のいずれかです。{public_domain} は、Commerce Cloud Digital サイト (たとえば www.example.com) にマッピングされている DNS 名です。{site_id} は、使用される実際のサイトの ID (たとえば SiteGenesis) です。
ベース URL は、Open Commerce API のメインアクセスポイントを提供します。このベース URL を拡張して特定のリソースにアクセスします。ベース URL を拡張する場合、次のパターンに従う必要があります。これらのパターンで表示される変数は以下で説明します。
最初のパターンで、リソースタイプの複数のリソースのアドレスを指定します:
2 つ目のパターンで、識別子を使用して 1 つのリソースのアドレスを指定します:
3 つ目のパターンで、アクションを指定して、リソース情報のアドレスを指定します:
4 つ目のパターンで、依存リソースの複数のインスタンスのアドレスを指定します:
5 つ目のパターンで、識別子を指定して、依存リソースからの情報のアドレスを指定します:
6 つ目のパターンで、アクションを指定して、依存リソースからの情報のアドレスを 指定します:
URL には ASCII 文字のみを使用します。予約されている ASCII 文字は、共通の "%" 表記を使用してエスケープします。
API バージョンは {version_id} で指定します。各 API バージョンでは、リソースタイプ ({resource_type})、リソースプロパティ、関係タイプ ({relationship_type})、およびアクション ({action}) がサポートされています。新しい API バージョンでは、新しいリソースタイプの追加、既存のリソースタイプへのプロパティの追加、以前サポートされていたリソースタイプの廃止、新しいセマンティクスや動作の導入を、構造を変更しなくても実行できます。
{version_id} は文字 "v" (小文字) で始まり、実際のバージョン番号がアンダースコアで区切られて続きます。例:
リソースタイプ ({resource_type}) は、RESTful API と同様、Open Commerce API の基礎となります。各リソースタイプには対応する一連のデータ (プロパティ、関係タイプ ({relationship_type})、およびアクション ({action}) が含まれます。リソースタイプのインスタンスは、Product や Basket といった Digital のオブジェクトに類似しています。
Open Commerce API では、各 API バージョンに一定のシステムリソースタイプのセットが用意されています。複数のリソースへのアクセスを提供するリソースタイプは、複数形の名前が指定されています (たとえば、"products")。1 つのリソースのみへのアクセスを提供するリソースタイプは、単数形の名前が指定されています (たとえば、"site")。次の URL の例では、識別子 ({identifier}) を使用してタイプ products のリソースが取得されます:
一意識別子 ({identifier}) によって、特定のリソースインスタンスをリクエストできます。次の URL では、ID (通常 SKU) を使用して商品リソースが検索されます。
{identifier} は URL エンコードする必要があります。次のエンコードされた URL で、予約された ASCII 文字 ("foo#bar" の "#" 文字) をエスケープします:
GET http://example.com/dw/shop/v23_1/products/foo%23bar
{identifier} の値を指定する場合、その値は次の制約に従う必要があります:
{identifier}のすべての値では大文字と小文字が区別されます。
products といった一部のリソースタイプでは、リクエスト URL に複数の識別子を指定して、複数のリソースをリクエストできます。こういったリクエストのレスポンスでは、Open Commerce API はリクエストされたリソースドキュメントの配列を含む結果オブジェクトを返します。
次の例は、複数の商品リソースのリクエスト方法を示します:
識別子のコンマ区切りリストは、かっこで囲む必要があります。
アクション ({action}) は、特定のリソースタイプ ({resource_type}) と関係タイプ ({relationship_type}) 上で動作します。アクションは通常すべてのリソースタイプと関係タイプで使用できません。アクションによって、たとえば顧客ログインなどの特別な操作が実行されます。
次の URL の例では、アクションを使用して顧客が認証されます (このアクションは顧客リソースタイプに固有です):
関係タイプ ({relationship_type}) は、他のリソースタイプ ({resource_type}) に依存するリソースタイプを表します。関係タイプによって、API は、1 つのリソース (たとえば、Product) と複数の依存リソース (たとえば、ProductLinks)の間の 1 対多関係を形作ることができます。各リソースタイプで関係タイプのサブセットを定義できます。このサブセットはリソースタイプで一意です。
次の URL の例では、買い物カゴに対してアイテムをリクエストします：
このリクエストでは、ID "12345" の買い物カゴに対してすべてのアイテムが返されます。