mirror of https://gitee.com/bigwinds/arangodb
141 lines
5.9 KiB
Markdown
141 lines
5.9 KiB
Markdown
////////////////////////////////////////////////////////////////////////////////
|
|
/// @startDocuBlock JSF_batch_processing
|
|
/// @brief executes a batch request
|
|
///
|
|
/// @RESTHEADER{POST /_api/batch,executes a batch request} /// TODOSWAGGER: contentype
|
|
///
|
|
/// @RESTALLBODYPARAM{body,string,required}
|
|
/// The multipart batch request, consisting of the envelope and the individual
|
|
/// batch parts.
|
|
///
|
|
/// @RESTDESCRIPTION
|
|
/// Executes a batch request. A batch request can contain any number of
|
|
/// other requests that can be sent to ArangoDB in isolation. The benefit of
|
|
/// using batch requests is that batching requests requires less client/server
|
|
/// roundtrips than when sending isolated requests.
|
|
///
|
|
/// All parts of a batch request are executed serially on the server. The
|
|
/// server will return the results of all parts in a single response when all
|
|
/// parts are finished.
|
|
///
|
|
/// Technically, a batch request is a multipart HTTP request, with
|
|
/// content-type `multipart/form-data`. A batch request consists of an
|
|
/// envelope and the individual batch part actions. Batch part actions
|
|
/// are "regular" HTTP requests, including full header and an optional body.
|
|
/// Multiple batch parts are separated by a boundary identifier. The
|
|
/// boundary identifier is declared in the batch envelope. The MIME content-type
|
|
/// for each individual batch part must be `application/x-arango-batchpart`.
|
|
///
|
|
/// Please note that when constructing the individual batch parts, you must
|
|
/// use CRLF (`\r\n`) as the line terminator as in regular HTTP messages.
|
|
///
|
|
/// The response sent by the server will be an `HTTP 200` response, with an
|
|
/// optional error summary header `x-arango-errors`. This header contains the
|
|
/// number of batch part operations that failed with an HTTP error code of at
|
|
/// least 400. This header is only present in the response if the number of
|
|
/// errors is greater than zero.
|
|
///
|
|
/// The response sent by the server is a multipart response, too. It contains
|
|
/// the individual HTTP responses for all batch parts, including the full HTTP
|
|
/// result header (with status code and other potential headers) and an
|
|
/// optional result body. The individual batch parts in the result are
|
|
/// seperated using the same boundary value as specified in the request.
|
|
///
|
|
/// The order of batch parts in the response will be the same as in the
|
|
/// original client request. Client can additionally use the `Content-Id`
|
|
/// MIME header in a batch part to define an individual id for each batch part.
|
|
/// The server will return this id is the batch part responses, too.
|
|
///
|
|
/// @RESTRETURNCODES
|
|
///
|
|
/// @RESTRETURNCODE{200}
|
|
/// is returned if the batch was received successfully. HTTP 200 is returned
|
|
/// even if one or multiple batch part actions failed.
|
|
///
|
|
/// @RESTRETURNCODE{400}
|
|
/// is returned if the batch envelope is malformed or incorrectly formatted.
|
|
/// This code will also be returned if the content-type of the overall batch
|
|
/// request or the individual MIME parts is not as expected.
|
|
///
|
|
/// @RESTRETURNCODE{405}
|
|
/// is returned when an invalid HTTP method is used.
|
|
///
|
|
/// @EXAMPLES
|
|
///
|
|
/// Sending a batch request with five batch parts:
|
|
///
|
|
/// - GET /_api/version
|
|
///
|
|
/// - DELETE /_api/collection/products
|
|
///
|
|
/// - POST /_api/collection/products
|
|
///
|
|
/// - GET /_api/collection/products/figures
|
|
///
|
|
/// - DELETE /_api/collection/products
|
|
///
|
|
/// The boundary (`SomeBoundaryValue`) is passed to the server in the HTTP
|
|
/// `Content-Type` HTTP header.
|
|
/// *Please note the reply is not displayed all accurate.*
|
|
///
|
|
/// @EXAMPLE_ARANGOSH_RUN{RestBatchMultipartHeader}
|
|
/// var parts = [
|
|
/// "Content-Type: application/x-arango-batchpart\r\n" +
|
|
/// "Content-Id: myId1\r\n\r\n" +
|
|
/// "GET /_api/version HTTP/1.1\r\n",
|
|
///
|
|
/// "Content-Type: application/x-arango-batchpart\r\n" +
|
|
/// "Content-Id: myId2\r\n\r\n" +
|
|
/// "DELETE /_api/collection/products HTTP/1.1\r\n",
|
|
///
|
|
/// "Content-Type: application/x-arango-batchpart\r\n" +
|
|
/// "Content-Id: someId\r\n\r\n" +
|
|
/// "POST /_api/collection/products HTTP/1.1\r\n\r\n" +
|
|
/// "{\"name\": \"products\" }\r\n",
|
|
///
|
|
/// "Content-Type: application/x-arango-batchpart\r\n" +
|
|
/// "Content-Id: nextId\r\n\r\n" +
|
|
/// "GET /_api/collection/products/figures HTTP/1.1\r\n",
|
|
///
|
|
/// "Content-Type: application/x-arango-batchpart\r\n" +
|
|
/// "Content-Id: otherId\r\n\r\n" +
|
|
/// "DELETE /_api/collection/products HTTP/1.1\r\n"
|
|
/// ];
|
|
/// var boundary = "SomeBoundaryValue";
|
|
/// var headers = { "Content-Type" : "multipart/form-data; boundary=" +
|
|
/// boundary };
|
|
/// var body = "--" + boundary + "\r\n" +
|
|
/// parts.join("\r\n" + "--" + boundary + "\r\n") +
|
|
/// "--" + boundary + "--\r\n";
|
|
///
|
|
/// var response = logCurlRequestRaw('POST', '/_api/batch', body, headers);
|
|
///
|
|
/// assert(response.code === 200);
|
|
///
|
|
/// logRawResponse(response);
|
|
/// @END_EXAMPLE_ARANGOSH_RUN
|
|
///
|
|
/// Sending a batch request, setting the boundary implicitly (the server will
|
|
/// in this case try to find the boundary at the beginning of the request body).
|
|
///
|
|
/// @EXAMPLE_ARANGOSH_RUN{RestBatchImplicitBoundary}
|
|
/// var parts = [
|
|
/// "Content-Type: application/x-arango-batchpart\r\n\r\n" +
|
|
/// "DELETE /_api/collection/notexisting1 HTTP/1.1\r\n",
|
|
/// "Content-Type: application/x-arango-batchpart\r\n\r\n" +
|
|
/// "DELETE _api/collection/notexisting2 HTTP/1.1\r\n"
|
|
/// ];
|
|
/// var boundary = "SomeBoundaryValue";
|
|
/// var body = "--" + boundary + "\r\n" +
|
|
/// parts.join("\r\n" + "--" + boundary + "\r\n") +
|
|
/// "--" + boundary + "--\r\n";
|
|
///
|
|
/// var response = logCurlRequestRaw('POST', '/_api/batch', body);
|
|
///
|
|
/// assert(response.code === 200);
|
|
/// assert(response.headers['x-arango-errors'] == 2);
|
|
///
|
|
/// logRawResponse(response);
|
|
/// @END_EXAMPLE_ARANGOSH_RUN
|
|
/// @endDocuBlock
|
|
//////////////////////////////////////////////////////////////////////////////// |