mirror of https://gitee.com/bigwinds/arangodb
427 lines
13 KiB
Plaintext
427 lines
13 KiB
Plaintext
!CHAPTER Managing Async Results via HTTP
|
|
|
|
@COMMENT{######################################################################}
|
|
@anchor HttpJobPut
|
|
@RESTHEADER{PUT /_api/job/`job-id`,Returns the result of an async job}
|
|
|
|
@RESTURLPARAMETERS
|
|
|
|
@RESTURLPARAM{job-id,string,required}
|
|
The async job id.
|
|
|
|
@RESTDESCRIPTION
|
|
Returns the result of an async job identified by `job-id`. If the async job
|
|
result is present on the server, the result will be removed from the list of
|
|
result. That means this method can be called for each `job-id` once.
|
|
|
|
The method will return the original job result's headers and body, plus the
|
|
additional HTTP header `x-arango-async-job-id`. If this header is present, then
|
|
the job was found and the response contains the original job's result. If the
|
|
header is not present, the job was not found and the response contains status
|
|
information from the job manager.
|
|
|
|
@RESTRETURNCODES
|
|
|
|
Any HTTP status code might be returned by this method. To tell the original job
|
|
response from a job manager response apart, check for the HTTP header
|
|
`x-arango-async-id`. If it is present, the response contains the original job's
|
|
result. Otherwise the response is from the job manager.
|
|
|
|
@RESTRETURNCODE{204}
|
|
is returned if the job requested via `job-id` is still in the queue of pending
|
|
(or not yet finished) jobs. In this case, no `x-arango-async-id` HTTP header
|
|
will be returned.
|
|
|
|
@RESTRETURNCODE{400}
|
|
is returned if no `job-id` was specified in the request. In this case, no
|
|
`x-arango-async-id` HTTP header will be returned.
|
|
|
|
@RESTRETURNCODE{404}
|
|
is returned if the job was not found or already deleted or fetched from the job
|
|
result list. In this case, no `x-arango-async-id` HTTP header will be returned.
|
|
|
|
@EXAMPLES
|
|
|
|
Not providing a job-id:
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestJobHandlerPutNone}
|
|
var url = "/_api/job/";
|
|
|
|
var response = logCurlRequest('PUT', url, "");
|
|
|
|
assert(response.code === 400);
|
|
logRawResponse(response);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
Providing a job-id for a non-existing job:
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestJobHandlerPutInvalid}
|
|
var url = "/_api/job/foobar";
|
|
|
|
var response = logCurlRequest('PUT', url, "");
|
|
|
|
assert(response.code === 404);
|
|
logRawResponse(response);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
Fetching the result of an HTTP GET job:
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestJobHandlerPutGet}
|
|
var url = "/_api/version";
|
|
|
|
var response = logCurlRequest('GET', url, "", { "x-arango-async": "store" });
|
|
|
|
assert(response.code === 202);
|
|
logRawResponse(response);
|
|
|
|
var id = response.headers['x-arango-async-id'];
|
|
require("internal").wait(1);
|
|
|
|
response = logCurlRequest('PUT', "/_api/job/" + id, "");
|
|
assert(response.code === 200);
|
|
assert(response.headers['x-arango-async-id'] === id);
|
|
logRawResponse(response);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
Fetching the result of an HTTP POST job that failed:
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestJobHandlerPutFail}
|
|
var url = "/_api/collection";
|
|
|
|
var response = logCurlRequest('POST', url, '{"name":" this name is invalid "}', { "x-arango-async": "store" });
|
|
|
|
assert(response.code === 202);
|
|
logRawResponse(response);
|
|
|
|
var id = response.headers['x-arango-async-id'];
|
|
require("internal").wait(1);
|
|
|
|
response = logCurlRequest('PUT', "/_api/job/" + id, "");
|
|
assert(response.code === 400);
|
|
assert(response.headers['x-arango-async-id'] === id);
|
|
logRawResponse(response);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
@RESTDONE
|
|
|
|
@COMMENT{######################################################################}
|
|
@CLEARPAGE
|
|
@anchor HttpJobPutCancel
|
|
@RESTHEADER{PUT /_api/job/`job-id`/cancel,Cancels an async job}
|
|
|
|
@RESTURLPARAMETERS
|
|
|
|
@RESTURLPARAM{job-id,string,required}
|
|
The async job id.
|
|
|
|
@RESTDESCRIPTION
|
|
Cancels the currently running job identified by `job-id`. Note that it still
|
|
might take some time to actually cancel the running async job.
|
|
|
|
@RESTRETURNCODES
|
|
|
|
Any HTTP status code might be returned by this method. To tell the original job
|
|
response from a job manager response apart, check for the HTTP header
|
|
`x-arango-async-id`. If it is present, the response contains the original job's
|
|
result. Otherwise the response is from the job manager.
|
|
|
|
@RESTRETURNCODE{200}
|
|
cancel has been initiated.
|
|
|
|
@RESTRETURNCODE{400}
|
|
is returned if no `job-id` was specified in the request. In this case, no
|
|
`x-arango-async-id` HTTP header will be returned.
|
|
|
|
@RESTRETURNCODE{404}
|
|
is returned if the job was not found or already deleted or fetched from the job
|
|
result list. In this case, no `x-arango-async-id` HTTP header will be returned.
|
|
|
|
@EXAMPLES
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestJobHandlerPutCancel}
|
|
var url = "/_api/cursor";
|
|
var body = '{"query": "FOR i IN 1..10 FOR j IN 1..10 LET x = sleep(1.0) FILTER i == 5 && j == 5 RETURN 42"}';
|
|
|
|
var response = logCurlRequest('POST', url, body, { "x-arango-async": "store" });
|
|
|
|
assert(response.code == 202);
|
|
logRawResponse(response);
|
|
|
|
var id = response.headers['x-arango-async-id'];
|
|
require("internal").wait(1);
|
|
|
|
response = logCurlRequest('GET', "/_api/job/pending", "", {});
|
|
logRawResponse(response);
|
|
|
|
response = logCurlRequest('PUT', "/_api/job/"+id+"/cancel", "", {});
|
|
logRawResponse(response);
|
|
|
|
response = logCurlRequest('GET', "/_api/job/pending", "", {});
|
|
logRawResponse(response);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
@RESTDONE
|
|
|
|
@COMMENT{######################################################################}
|
|
@CLEARPAGE
|
|
@anchor HttpJobDelete
|
|
@RESTHEADER{DELETE /_api/job/`type`,Deletes the result of async jobs}
|
|
|
|
@RESTURLPARAMETERS
|
|
|
|
@RESTURLPARAM{type,string,required}
|
|
The type of jobs to delete. `type` can be:
|
|
- `all`: deletes all jobs results. Currently executing or queued async jobs
|
|
will not be stopped by this call.
|
|
- `expired`: deletes expired results. To determine the expiration status of
|
|
a result, pass the `stamp` URL parameter. `stamp` needs to be a UNIX
|
|
timestamp, and all async job results created at a lower timestamp will be
|
|
deleted.
|
|
- an actual job-id: in this case, the call will remove the result of the
|
|
specified async job. If the job is currently executing or queued, it will
|
|
not be aborted.
|
|
|
|
@RESTQUERYPARAMETERS
|
|
|
|
@RESTQUERYPARAM{stamp,number,optional}
|
|
A UNIX timestamp specifying the expiration threshold when type is `expired`.
|
|
|
|
@RESTDESCRIPTION
|
|
Deletes either all job results, expired job results, or the result of a specific
|
|
job. Clients can use this method to perform an eventual garbage collection of
|
|
job results.
|
|
|
|
@RESTRETURNCODES
|
|
|
|
@RESTRETURNCODE{200}
|
|
is returned if the deletion operation was carried out successfully. This code
|
|
will also be returned if no results were deleted.
|
|
|
|
@RESTRETURNCODE{400}
|
|
is returned if `type` is not specified or has an invalid value.
|
|
|
|
@RESTRETURNCODE{404}
|
|
is returned if `type` is a job-id but no async job with the specified id was
|
|
found.
|
|
|
|
@EXAMPLES
|
|
|
|
Deleting all jobs:
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestJobHandlerDeleteAll}
|
|
var url = "/_api/version";
|
|
|
|
var response = logCurlRequest('GET', url, "", { "x-arango-async": "store" });
|
|
|
|
assert(response.code === 202);
|
|
logRawResponse(response);
|
|
|
|
require("internal").wait(1);
|
|
|
|
response = logCurlRequest('DELETE', "/_api/job/all");
|
|
assert(response.code === 200);
|
|
logJsonResponse(response);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
Deleting expired jobs:
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestJobHandlerDeleteExpired}
|
|
var url = "/_api/version";
|
|
|
|
var response = logCurlRequest('GET', url, "", { "x-arango-async": "store" });
|
|
|
|
assert(response.code === 202);
|
|
logRawResponse(response);
|
|
|
|
require("internal").wait(1);
|
|
var stamp = parseInt(require("internal").time() + 360, 10);
|
|
|
|
response = logCurlRequest('DELETE', "/_api/job/expired?stamp=" + stamp);
|
|
assert(response.code === 200);
|
|
logJsonResponse(response);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
Deleting the result of a specific job:
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestJobHandlerDeleteId}
|
|
var url = "/_api/version";
|
|
|
|
var response = logCurlRequest('GET', url, "", { "x-arango-async": "store" });
|
|
|
|
assert(response.code === 202);
|
|
logRawResponse(response);
|
|
|
|
var id = response.headers['x-arango-async-id'];
|
|
require("internal").wait(1);
|
|
|
|
response = logCurlRequest('DELETE', "/_api/job/" + id);
|
|
assert(response.code === 200);
|
|
logJsonResponse(response);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
Deleting the result of a non-existing job:
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestJobHandlerDeleteInvalid}
|
|
response = logCurlRequest('DELETE', "/_api/job/foobar");
|
|
assert(response.code === 404);
|
|
logJsonResponse(response);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
@RESTDONE
|
|
|
|
@COMMENT{######################################################################}
|
|
@CLEARPAGE
|
|
@anchor HttpJobGetId
|
|
@RESTHEADER{GET /_api/job/`job-id`,Returns the status of the specified job}
|
|
|
|
@RESTURLPARAMETERS
|
|
|
|
@RESTURLPARAM{job-id,string,required}
|
|
The async job id.
|
|
|
|
@RESTDESCRIPTION
|
|
Returns the processing status of the specified job. The processing status can be
|
|
determined by peeking into the HTTP response code of the response.
|
|
|
|
@RESTRETURNCODES
|
|
|
|
@RESTRETURNCODE{200}
|
|
is returned if the job requested via `job-id` has been executed successfully and
|
|
its result is ready to fetch.
|
|
|
|
@RESTRETURNCODE{204}
|
|
is returned if the job requested via `job-id` is still in the queue of pending
|
|
(or not yet finished) jobs.
|
|
|
|
@RESTRETURNCODE{400}
|
|
is returned if no `job-id` was specified in the request.
|
|
|
|
@RESTRETURNCODE{404}
|
|
is returned if the job was not found or already deleted or fetched from the job
|
|
result list.
|
|
|
|
@EXAMPLES
|
|
|
|
Querying the status of a done job:
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestJobHandlerGetIdDone}
|
|
var url = "/_api/version";
|
|
|
|
var response = logCurlRequest('GET', url, "", { "x-arango-async": "store" });
|
|
|
|
assert(response.code === 202);
|
|
var id = response.headers['x-arango-async-id'];
|
|
logRawResponse(response);
|
|
|
|
require("internal").wait(1);
|
|
|
|
response = logCurlRequest('GET', "/_api/job/" + id);
|
|
assert(response.code === 200 || response.code === 204);
|
|
logRawResponse(response);
|
|
|
|
response = curlRequest('DELETE', "/_api/job/" + id);
|
|
assert(response.code === 200);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
Querying the status of a pending job:
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestJobHandlerGetIdPending}
|
|
var url = "/_admin/sleep?duration=3";
|
|
|
|
var response = logCurlRequest('GET', url, "", { "x-arango-async": "store" });
|
|
|
|
assert(response.code === 202);
|
|
var id = response.headers['x-arango-async-id'];
|
|
logRawResponse(response);
|
|
|
|
response = logCurlRequest('GET', "/_api/job/" + id);
|
|
assert(response.code === 204);
|
|
logRawResponse(response);
|
|
|
|
response = curlRequest('DELETE', "/_api/job/" + id);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
@RESTDONE
|
|
|
|
@COMMENT{######################################################################}
|
|
@CLEARPAGE
|
|
@anchor HttpJobGetType
|
|
|
|
@RESTHEADER{GET /_api/job/`type`,Returns the list of job result ids with a specific status}
|
|
|
|
@RESTURLPARAMETERS
|
|
|
|
@RESTURLPARAM{type,string,required}
|
|
The type of jobs to return. The type can be either `done` or `pending`. Setting
|
|
the type to `done` will make the method return the ids of already completed
|
|
async jobs for which results can be fetched. Setting the type to `pending` will
|
|
return the ids of not yet finished async jobs.
|
|
|
|
@RESTQUERYPARAMETERS
|
|
|
|
@RESTQUERYPARAM{count,number,optional}
|
|
The maximum number of ids to return per call. If not specified, a server-defined
|
|
maximum value will be used.
|
|
|
|
@RESTDESCRIPTION
|
|
Returns the list of ids of async jobs with a specific status (either done or
|
|
pending). The list can be used by the client to get an overview of the job
|
|
system status and to retrieve completed job results later.
|
|
|
|
@RESTRETURNCODES
|
|
|
|
@RESTRETURNCODE{200}
|
|
is returned if the list can be compiled successfully. Note: the list might be
|
|
empty.
|
|
|
|
@RESTRETURNCODE{400}
|
|
is returned if `type` is not specified or has an invalid value.
|
|
|
|
@EXAMPLES
|
|
|
|
Fetching the list of done jobs:
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestJobHandlerGetDone}
|
|
var url = "/_api/version";
|
|
|
|
var response = logCurlRequest('GET', url, "", { "x-arango-async": "store" });
|
|
|
|
assert(response.code === 202);
|
|
logRawResponse(response);
|
|
|
|
require("internal").wait(1);
|
|
|
|
response = logCurlRequest('GET', "/_api/job/done");
|
|
assert(response.code === 200);
|
|
logJsonResponse(response);
|
|
|
|
response = curlRequest('DELETE', "/_api/job/all");
|
|
assert(response.code === 200);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
Fetching the list of pending jobs:
|
|
|
|
@EXAMPLE_ARANGOSH_RUN{RestJobHandlerGetPending}
|
|
var url = "/_api/version";
|
|
|
|
var response = logCurlRequest('GET', url, "", { "x-arango-async": "store" });
|
|
|
|
assert(response.code === 202);
|
|
logRawResponse(response);
|
|
|
|
var id = response.headers['x-arango-async-id'];
|
|
require("internal").wait(1);
|
|
|
|
response = logCurlRequest('GET', "/_api/job/pending");
|
|
assert(response.code === 200);
|
|
logJsonResponse(response);
|
|
|
|
response = curlRequest('DELETE', "/_api/job/all");
|
|
assert(response.code === 200);
|
|
@END_EXAMPLE_ARANGOSH_RUN
|
|
|
|
@RESTDONE
|
|
|
|
@COMMENT{######################################################################}
|
|
|