OCAPI バッチリクエスト 23.1

OCAPI バッチリクエストは、最高で 50 件のサブリクエストを含むことのできるマルチパート HTTP リクエストです。各サブリクエスト (パート) は、単一のリソースで処理を行うことが必要です。複数の ID を指定するサブリクエスト (たとえば、'/products/(p1,p2...)') は禁じられています。

バッチリクエストは、送信される全体的な情報量と必要な呼び出しの回数を減らすことで、ネットワークののオーバーヘッドを削減します。たとえば、アプリケーションの画面を作成するために、多数の小さな OCAPI リクエストを個々に作成する代わりに、単一の大きなマルチパートバッチリクエストを作成できます。

バッチリクエストに使用する HTTP メソッドは、全体として POST または OPTIONS であることが必要です。後続のサブリクエストでは、必要に応じて異なる HTTP メソッドを指定できます。

各バッチリクエストは、メインヘッダーセクションをもちます。このセクションには、タイプ (multipart/mixed) と、各サブリクエストを区切るのに使用される境界区切り文字を指定する Content-Type ヘッダーを含める必要があります。例:

バッチリクエストのメインヘッダーセクションに含まれる各ヘッダーは、各サブリクエストに暗黙的に継承されます。メインバッチリクエストのクエリパラメーターも、各サブリクエストに暗黙的に継承されます。

ただし、各サブリクエストは概念的には完全な OCAPI リクエストで、独自のリソースパス、ヘッダーセクション、およびリクエストボディをもちます。必要であれば、サブリクエストは継承したヘッダーと継承したクエリパラメーターを上書きできます。

サブリクエストの動作を指定し、リクエストとレスポンス間のマッピングを定義するために、必要に応じて次のヘッダーを指定する必要があります。

ヘッダー名	場所	説明
`x-dw-http-method`	リクエスト、サブリクエスト	リソースへのアクセスに使用される HTTP メソッドを指定します。
`x-dw-resource-path`	リクエスト、サブリクエスト	ベースリソースパスを指定します。このヘッダーの値が `x-dw-resource-path-extension` ヘッダーと組み合わされて、完全なリソースパスが提供されます。
`x-dw-resource-path-extension`	リクエスト、サブリクエスト	`x-dw-resource-path` ヘッダーによって指定されたベースパスの値の拡張を指定します。ベースリソースパスがすでに有効な OCAPI リソースを表している場合は、このヘッダーはオプションです。
`x-dw-content-id`	サブリクエスト、サブレスポンス	サブリクエストの ID を指定します。このヘッダー値は、サブリクエストをサブレスポンスにマップするのに使用されます。
`x-dw-status-code`	サブレスポンス	1 つのサブレスポンスのステータスコードを指定します。

バッチリクエストは CORS をサポートしています。使用可能な公開のヘッダーと起点は、各クライアント ID の OCAPI 設定に言及されています。これらにアクセスするには、特定のサイトまたはグローバルのいずれかのコンテキストで、特定のクライアントのバッチリクエストを送信する必要があります。クライアント ID を渡すには、次のいくつかの方法があります。

クライアント ID をクエリパラメーターとして
クライアント ID を x-dw-client-id ヘッダーとして
OAuth アクセストークンを Authorization ヘッダーを通じて
JWT を Authorization ヘッダーを通じて

標準に準拠するバッチリクエストボディ内のサブリクエストは、Multipart Media Type (マルチパートメディアタイプ) で定義されます。このアプローチでは、マルチパートサブリクエストのヘッダーセクションが、マルチパートの境界のすぐ後に続くことが必要です。ヘッダーセクションとマルチパートボディセクションは、後に続く 2 つの改行文字で区切る必要があります。

例 1

サブリクエストの正しい形式。

例 2

サブリクエストの正しくない形式。ヘッダーセクションの後に改行が 1 つのみ。

例 3

サブリクエストの正しくない形式。境界の後に 2 つの下位行があると、ヘッダーセクションが空になります。

例 1

以下の例は、同じタイプの複数のリソースにアクセスする方法を示しています。

例 2

以下の例は、異なるタイプのリソースにアクセスする方法を示しています。

各リクエストのサイトコンテキストは、x-dw-resource-path または x-dw-resource-path-extension で定義できます。これらのヘッダーでサイトコンテキストが指定されていない場合は、メインリクエストのコンテキストが使用されます。これは、メインリクエストのサイトコンテキストは、リソースパスヘッダーで上書きできることを示唆しています。

バッチリクエストボディのサイズは 5 MB に制限されています。サブリクエストの最大数は 50 です。

例外名	ステータスコード	説明
`IllegalContentTypeException`	400	リクエストコンテンツタイプが multipart/mixed でない場合、または境界が指定されていない場合にスローされます。
`IllegalQueryStringException`	400	リクエストまたはサブリクエストのクエリ文字列が無効な場合にスローされます。
`InvalidAuthorizationHeaderException`	401	認証ヘッダーが Authorization ... の形式でない場合にスローされます。
`InvalidHttpMethodException`	400	リクエストヘッダーまたはサブリクエストヘッダーの HTTP メソッドが無効な場合にスローされます。
`InvalidRequestBodyException`	400	リクエストボディが無効な場合にスローされます。
`InvalidTokenException`	401	Authorization: Bearer ヘッダーで送信されたトークンが無効か、有効期限が切れています。
`MethodNotAllowedException`	405	リクエストが POST または OPTIONS 以外の HTTP メソッドで送信された場合にスローされます。
`MissingClientIdException`	400	メインリクエストで (クライアント ID または認証トークンとして) クライアント ID が送信されなかった場合にスローされます。
`MissingHttpMethodException`	400	HTTP メソッドのないサブリクエストが少なくとも 1 つある場合にスローされます。
`MissingResourcePathException`	400	リソースパスのないサブリクエストが少なくとも 1 つある場合にスローされます。
`QuotaExceededException`	400	バッチリクエストに 50 を超えるサブリクエストがある場合にスローされます。
`RequestEntityTooLargeException`	400	バッチリクエストボディが 5MB を超える場合にスローされます。
`ResourcePathNotAllowedException`	400	複数 ID のリソース呼び出しであるサブリクエストが少なくとも 1 つある場合にスローされます。
`UnauthorizedOriginException`	401	クライアントへのアクセスのための OCAPI 設定で、与えられた起点が言及されていない場合にスローされます。
`UnknownClientIdException`	401	与えられたクライアント ID が Account Manager で不明の場合にスローされます。
`UnknownSiteIdException`	400	サイト名が不明のコンテキストでリクエストが送信された場合にスローされます。