mirror of https://gitee.com/bigwinds/arangodb
388 lines
10 KiB
Plaintext
388 lines
10 KiB
Plaintext
!CHAPTER Managing Async Results via HTTP
|
|
|
|
`PUT /_api/job/job-id`*(Returns the result of an async job)*
|
|
|
|
!SUBSECTION URL parameters
|
|
|
|
`job-id (string,required)`
|
|
|
|
The async job id.
|
|
|
|
!SUBSECTION Description
|
|
|
|
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 amanger.
|
|
|
|
!SUBSECTION Return codes
|
|
|
|
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.
|
|
|
|
`HTTP 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.
|
|
|
|
`HTTP 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.
|
|
|
|
`HTTP 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:
|
|
|
|
```
|
|
unix> curl -X PUT --dump - http://localhost:8529/_api/job/
|
|
|
|
HTTP/1.1 400 Bad Request
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{"error":true,"errorMessage":"bad parameter","code":400,"errorNum":400}
|
|
```
|
|
|
|
Providing a job-id for a non-existing job:
|
|
|
|
```
|
|
unix> curl -X PUT --dump - http://localhost:8529/_api/job/foobar
|
|
|
|
HTTP/1.1 404 Not Found
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{"error":true,"errorMessage":"not found","code":404,"errorNum":404}
|
|
```
|
|
|
|
Fetching the result of an HTTP GET job:
|
|
|
|
```
|
|
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
|
|
|
|
HTTP/1.1 202 Accepted
|
|
content-type: text/plain; charset=utf-8
|
|
x-arango-async-id: 265413601
|
|
|
|
unix> curl -X PUT --dump - http://localhost:8529/_api/job/265413601
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
x-arango-async-id: 265413601
|
|
|
|
{"server":"arango","version":"2.1.0"}
|
|
```
|
|
|
|
Fetching the result of an HTTP POST job that failed:
|
|
|
|
```
|
|
unix> curl -X POST --header 'x-arango-async: store' --data-binary @- --dump - http://localhost:8529/_api/collection
|
|
{"name":" this name is invalid "}
|
|
|
|
HTTP/1.1 202 Accepted
|
|
content-type: text/plain; charset=utf-8
|
|
x-arango-async-id: 265479137
|
|
|
|
unix> curl -X PUT --dump - http://localhost:8529/_api/job/265479137
|
|
|
|
HTTP/1.1 400 Bad Request
|
|
content-type: application/json; charset=utf-8
|
|
x-arango-async-id: 265479137
|
|
|
|
{"error":true,"code":400,"errorNum":1208,"errorMessage":"cannot create collection: illegal name"}
|
|
```
|
|
|
|
`PUT /_api/job/job-id/cancel`*(Cancels an async job)*
|
|
|
|
!SUBSECTION URL parameters
|
|
|
|
`job-id (string,required)`
|
|
|
|
The async job id.
|
|
|
|
!SUBSECTION Description
|
|
|
|
Cancels the currently running job identified by job-id. Note that it still might take some time to actually cancel the running async job.
|
|
|
|
!SUBSECTION Return codes
|
|
|
|
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.
|
|
|
|
`HTTP 200`
|
|
|
|
cancel has been initiated.
|
|
|
|
`HTTP 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.
|
|
|
|
`HTTP 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*
|
|
|
|
```
|
|
unix> curl -X POST --header 'x-arango-async: store' --data-binary @- --dump - http://localhost:8529/_api/cursor
|
|
{"query": "FOR i IN 1..10 FOR j IN 1..10 LET x = sleep(1.0) FILTER i == 5 && j == 5 RETURN 42"}
|
|
|
|
HTTP/1.1 202 Accepted
|
|
content-type: text/plain; charset=utf-8
|
|
x-arango-async-id: 268952545
|
|
|
|
unix> curl --dump - http://localhost:8529/_api/job/pending
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
["268952545"]
|
|
|
|
unix> curl -X PUT --dump - http://localhost:8529/_api/job/268952545/cancel
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{"result":true}
|
|
|
|
unix> curl --dump - http://localhost:8529/_api/job/pending
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
["268952545"]
|
|
```
|
|
|
|
`DELETE /_api/job/type`*(Deletes the result of async jobs)*
|
|
|
|
!SUBSECTION URL parameters
|
|
|
|
`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.
|
|
|
|
!SUBSECTION Query parameters
|
|
|
|
`stamp (number,optional)`
|
|
|
|
A UNIX timestamp specifying the expiration threshold when type is expired.
|
|
|
|
!SUBSECTION Description
|
|
|
|
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.
|
|
|
|
!SUBSECTION Return codes
|
|
|
|
`HTTP 200`
|
|
|
|
is returned if the deletion operation was carried out successfully. This code will also be returned if no results were deleted.
|
|
|
|
`HTTP 400`
|
|
|
|
is returned if type is not specified or has an invalid value.
|
|
|
|
`HTTP 404`
|
|
|
|
is returned if type is a job-id but no async job with the specified id was found.
|
|
|
|
*Examples*
|
|
|
|
Deleting all jobs:
|
|
|
|
```
|
|
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
|
|
|
|
HTTP/1.1 202 Accepted
|
|
content-type: text/plain; charset=utf-8
|
|
x-arango-async-id: 270132193
|
|
|
|
unix> curl -X DELETE --dump - http://localhost:8529/_api/job/all
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{
|
|
"result" : true
|
|
}
|
|
```
|
|
|
|
Deleting expired jobs:
|
|
|
|
```
|
|
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
|
|
|
|
HTTP/1.1 202 Accepted
|
|
content-type: text/plain; charset=utf-8
|
|
x-arango-async-id: 270197729
|
|
|
|
unix> curl -X DELETE --dump - http://localhost:8529/_api/job/expired?stamp=1401376184
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{
|
|
"result" : true
|
|
}
|
|
```
|
|
|
|
Deleting the result of a specific job:
|
|
|
|
```
|
|
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
|
|
|
|
HTTP/1.1 202 Accepted
|
|
content-type: text/plain; charset=utf-8
|
|
x-arango-async-id: 270263265
|
|
|
|
unix> curl -X DELETE --dump - http://localhost:8529/_api/job/270263265
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{
|
|
"result" : true
|
|
}
|
|
```
|
|
|
|
Deleting the result of a non-existing job:
|
|
|
|
```
|
|
unix> curl -X DELETE --dump - http://localhost:8529/_api/job/foobar
|
|
|
|
HTTP/1.1 404 Not Found
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{
|
|
"error" : true,
|
|
"errorMessage" : "not found",
|
|
"code" : 404,
|
|
"errorNum" : 404
|
|
}
|
|
```
|
|
|
|
`GET /_api/job/job-id`*(Returns the status of the specified job)*
|
|
|
|
!SUBSECTION URL parameters
|
|
|
|
`job-id (string,required)`
|
|
|
|
The async job id.
|
|
|
|
!SUBSECTION Description
|
|
|
|
Returns the processing status of the specified job. The processing status can be determined by peeking into the HTTP response code of the response.
|
|
!SUBSECTION Return codes
|
|
|
|
`HTTP 200`
|
|
|
|
is returned if the job requested via job-id has been executed successfully and its result is ready to fetch.
|
|
|
|
`HTTP 204`
|
|
|
|
is returned if the job requested via job-id is still in the queue of pending (or not yet finished) jobs.
|
|
|
|
`HTTP 400`
|
|
|
|
is returned if no job-id was specified in the request.
|
|
|
|
`HTTP 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:
|
|
|
|
```
|
|
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
|
|
|
|
HTTP/1.1 202 Accepted
|
|
content-type: text/plain; charset=utf-8
|
|
x-arango-async-id: 270328801
|
|
|
|
unix> curl --dump - http://localhost:8529/_api/job/270328801
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: text/plain; charset=utf-8
|
|
|
|
Querying the status of a pending job:
|
|
|
|
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_admin/sleep?duration=3
|
|
|
|
HTTP/1.1 202 Accepted
|
|
content-type: text/plain; charset=utf-8
|
|
x-arango-async-id: 270394337
|
|
|
|
unix> curl --dump - http://localhost:8529/_api/job/270394337
|
|
|
|
HTTP/1.1 204 No Content
|
|
content-type: text/plain; charset=utf-8
|
|
```
|
|
|
|
`GET /_api/job/type`*(Returns the list of job result ids with a specific status)*
|
|
|
|
!SUBSECTION URL parameters
|
|
|
|
`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.
|
|
|
|
!SUBSECTION Query parameters
|
|
|
|
`count (number,optional)`
|
|
|
|
The maximum number of ids to return per call. If not specified, a server-defined maximum value will be used.
|
|
|
|
!SUBSECTION Description
|
|
|
|
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.
|
|
|
|
!SUBSECTION Return codes
|
|
|
|
`HTTP 200`
|
|
|
|
is returned if the list can be compiled successfully. Note: the list might be empty.
|
|
|
|
`HTTP 400`
|
|
|
|
is returned if type is not specified or has an invalid value.
|
|
|
|
*Examples*
|
|
|
|
Fetching the list of done jobs:
|
|
|
|
```
|
|
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
|
|
|
|
HTTP/1.1 202 Accepted
|
|
content-type: text/plain; charset=utf-8
|
|
x-arango-async-id: 270459873
|
|
|
|
unix> curl --dump - http://localhost:8529/_api/job/done
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
[
|
|
"270459873"
|
|
]
|
|
```
|
|
|
|
Fetching the list of pending jobs:
|
|
|
|
```
|
|
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
|
|
|
|
HTTP/1.1 202 Accepted
|
|
content-type: text/plain; charset=utf-8
|
|
x-arango-async-id: 270525409
|
|
|
|
unix> curl --dump - http://localhost:8529/_api/job/pending
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
[ ]
|
|
```
|