OCAPI バッチリクエストは、最高で 50 件のサブリクエストを含むことのできるマルチパート HTTP リクエストです。各サブリクエスト (パート) は、単一のリソースで処理を行うことが必要です。複数の ID を指定するサブリクエスト (たとえば、'/products/(p1,p2...)') は禁じられています。
バッチリクエストは、送信される全体的な情報量と必要な呼び出しの回数を減らすことで、ネットワークののオーバーヘッドを削減します。たとえば、アプリケーションの画面を作成するために、多数の小さな OCAPI リクエストを個々に作成する代わりに、単一の大きなマルチパートバッチリクエストを作成できます。
バッチリクエストに使用する HTTP メソッドは、全体として POST または OPTIONS であることが必要です。後続のサブリクエストでは、必要に応じて異なる HTTP メソッドを指定できます。
各バッチリクエストは、メインヘッダーセクションをもちます。このセクションには、タイプ (multipart/mixed) と、各サブリクエストを区切るのに使用される境界区切り文字を指定する Content-Type ヘッダーを含める必要があります。例:
1Content-Type: multipart/mixed; boundary=23dh3f9f4バッチリクエストのメインヘッダーセクションに含まれる各ヘッダーは、各サブリクエストに暗黙的に継承されます。メインバッチリクエストのクエリパラメーターも、各サブリクエストに暗黙的に継承されます。
ただし、各サブリクエストは概念的には完全な 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 を渡すには、次のいくつかの方法があります。
標準に準拠するバッチリクエストボディ内のサブリクエストは、Multipart Media Type (マルチパートメディアタイプ) で定義されます。このアプローチでは、マルチパートサブリクエストのヘッダーセクションが、マルチパートの境界のすぐ後に続くことが必要です。ヘッダーセクションとマルチパートボディセクションは、後に続く 2 つの改行文字で区切る必要があります。
例 1
サブリクエストの正しい形式。
1REQUEST:
2 POST /batch HTTP 1.1
3 Host: example.com
4 Content-Type: multipart/mixed; boundary=23dh3f9f4
5 Authorization: Bearer f9f34f43rfdf0isadjf93059j4
6 x-dw-http-method: DELETE
7 x-dw-resource-path: /s/-/dw/data/v23_1/libraries/SiteGenesis/content/
8 --23dh3f9f4\n
9 x-dw-content-id: realCount\n
10 \n
11 {"query":{"filtered_query":{"query":{"bool_query":{"must":[{"term_query":{"fields":["product_items.product_id"],"operator":"one_of","values":["S20273_100"]}},{"term_query":{"fields":["status"],"operator":"one_of","values":["new"]}}]}},"filter":{"range_filter":{"field":"creation_date","from":"2020-04-01"}}}},"select":"(total)"}\n
12 --23dh3f9f4--
13 ...例 2
サブリクエストの正しくない形式。ヘッダーセクションの後に改行が 1 つのみ。
1REQUEST:
2 POST /batch HTTP 1.1
3 Host: example.com
4 Content-Type: multipart/mixed; boundary=23dh3f9f4
5 Authorization: Bearer f9f34f43rfdf0isadjf93059j4
6 x-dw-http-method: DELETE
7 x-dw-resource-path: /s/-/dw/data/v23_1/libraries/SiteGenesis/content/
8 -23dh3f9f4\n
9 x-dw-content-id: realCount\n
10 {"query":{"filtered_query":{"query":{"bool_query":{"must":[{"term_query":{"fields":["product_items.product_id"],"operator":"one_of","values":["S20273_100"]}},{"term_query":{"fields":["status"],"operator":"one_of","values":["new"]}}]}},"filter":{"range_filter":{"field":"creation_date","from":"2020-04-01"}}}},"select":"(total)"}\n
11 --23dh3f9f4--
12 ...例 3
サブリクエストの正しくない形式。境界の後に 2 つの下位行があると、ヘッダーセクションが空になります。
1REQUEST:
2 POST /batch HTTP 1.1
3 Host: example.com
4 Content-Type: multipart/mixed; boundary=23dh3f9f4
5 Authorization: Bearer f9f34f43rfdf0isadjf93059j4
6 x-dw-http-method: DELETE
7 x-dw-resource-path: /s/-/dw/data/v23_1/libraries/SiteGenesis/content/
8 --23dh3f9f4\n
9 \n
10 x-dw-content-id: realCount\n
11 {"query":{"filtered_query":{"query":{"bool_query":{"must":[{"term_query":{"fields":["product_items.product_id"],"operator":"one_of","values":["S20273_100"]}},{"term_query":{"fields":["status"],"operator":"one_of","values":["new"]}}]}},"filter":{"range_filter":{"field":"creation_date","from":"2020-04-01"}}}},"select":"(total)"}\n
12 --23dh3f9f4--
13 ...例 1
以下の例は、同じタイプの複数のリソースにアクセスする方法を示しています。
1REQUEST:
2 POST /batch HTTP 1.1
3 Host: example.com
4 Content-Type: multipart/mixed; boundary=23dh3f9f4
5 Authorization: Bearer f9f34f43rfdf0isadjf93059j4
6 x-dw-http-method: DELETE
7 x-dw-resource-path: /s/-/dw/data/v23_1/libraries/SiteGenesis/content/
8
9 --23dh3f9f4
10 x-dw-content-id: req1
11 x-dw-resource-path-extension: content_asset_1
12 --23dh3f9f4
13 ...
14 x-dw-content-id: req50
15 x-dw-resource-path-extension: content_asset_50
16 --23dh3f9f4--
17
18 RESPONSE:
19 HTTP/1.1 200 OK
20 Content-Type: multipart/mixed; boundary=23dh3f9f4
21
22 --23dh3f9f4
23 x-dw-content-id: req1
24 x-dw-status-code: 204
25 --23dh3f9f4
26 ...
27 x-dw-content-id: req50
28 x-dw-status-code: 204
29 --23dh3f9f4--例 2
以下の例は、異なるタイプのリソースにアクセスする方法を示しています。
1REQUEST:
2 POST /batch HTTP 1.1
3 Host: example.com
4 Content-Type: multipart/mixed; boundary=23dh3f9f4
5 x-dw-client-id: [your_own_client_id]
6 x-dw-http-method: GET
7 x-dw-resource-path: /s/SiteGenesis/dw/shop/v23_1/
8
9 --23dh3f9f4
10 x-dw-content-id: req_addr_create
11 x-dw-http-method: PUT
12 x-dw-resource-path-extension: account/this/addresses
13
14 {
15 "address1":"10 Somewhere St.",
16 "city":"Boston",
17 "last_name":"Lebowski",
18 "country_code":"US",
19 "postal_code":"98765",
20 "state_code":"MA"
21 }
22 --23dh3f9f4
23 x-dw-content-id: req_prod_get
24 x-dw-resource-path-extension: products/creative-zen-v
25 --23dh3f9f4--
26
27 RESPONSE:
28 HTTP/1.1 200 OK
29 Content-Type: multipart/mixed; boundary=23dh3f9f4
30
31 --23dh3f9f4
32 x-dw-content-id: req_addr_create
33 x-dw-status-code: 200
34
35 {
36 "_v" : "23.1",
37 "_type":"customer_address",
38 "address1":"10 Somewhere St.",
39 "address_id":"84619.10625703718",
40 "city":"Boston",
41 "country_code":"US",
42 "last_name":"Lebowski",
43 "postal_code":"98765",
44 "state_code":"MA"
45 }
46 --23dh3f9f4
47 x-dw-content-id: req_prod_get
48 x-dw-status-code: 404
49
50 {
51 "_v" : "23.1",
52 "fault":{
53 "type":"ProductNotFoundException",
54 "message":"No product with id 'creative-zen-v' for site 'SiteGenesis' found."
55 }
56 }
57 --23dh3f9f4--各リクエストのサイトコンテキストは、x-dw-resource-path または x-dw-resource-path-extension で定義できます。これらのヘッダーでサイトコンテキストが指定されていない場合は、メインリクエストのコンテキストが使用されます。これは、メインリクエストのサイトコンテキストは、リソースパスヘッダーで上書きできることを示唆しています。
バッチリクエストボディのサイズは 5 MB に制限されています。サブリクエストの最大数は 50 です。
| 例外名 | ステータスコード | 説明 |
|---|---|---|
IllegalContentTypeException | 400 | リクエストコンテンツタイプが multipart/mixed でない場合、または境界が指定されていない場合にスローされます。 |
IllegalQueryStringException | 400 | リクエストまたはサブリクエストのクエリ文字列が無効な場合にスローされます。 |
InvalidAuthorizationHeaderException | 401 | 認証ヘッダーが Authorization:Bearer … の形式でない場合にスローされます。 |
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 | サイト名が不明のコンテキストでリクエストが送信された場合にスローされます。 |
j