X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/441549528f2fcea8e55fde62416a69f2bfc6816d..f71c9e59bfff91da4b89050ceae27dbe3edcdb6c:/doc/api/methods/jobs.html.textile.liquid?ds=sidebyside diff --git a/doc/api/methods/jobs.html.textile.liquid b/doc/api/methods/jobs.html.textile.liquid index 5d0b187a9f..d75977a5f5 100644 --- a/doc/api/methods/jobs.html.textile.liquid +++ b/doc/api/methods/jobs.html.textile.liquid @@ -6,14 +6,15 @@ title: "jobs" ... +See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html +API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/jobs@ Required arguments are displayed in %{background:#ccffcc}green%. - h2. cancel -cancel jobs +Cancel a job that is queued or running. Arguments: @@ -29,12 +30,15 @@ Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | -{background:#ccffcc}.|job|object|See "Job resource":{{site.baseurl}}/schema/Job.html|request body|| -|minimum_script_version |string |Git branch, tag, or commit hash specifying the minimum acceptable script version (earliest ancestor) to consider when deciding whether to re-use a past job.|query|@c3e86c9@| -|exclude_script_versions|array of strings|Git commit branches, tags, or hashes to exclude when deciding whether to re-use a past job.|query|@["8f03c71","8f03c71"]@| -|no_reuse |boolean |Disable implicit "find or create" feature: run a new job, even if a job is available with identical script, version, and parameters.|query|@false@| +{background:#ccffcc}.|job|object|See "Job resource":{{site.baseurl}}/api/schema/Job.html|request body|| +|minimum_script_version |string |Git branch, tag, or commit hash specifying the minimum acceptable script version (earliest ancestor) to consider when deciding whether to re-use a past job.[1]|query|@"c3e86c9"@| +|exclude_script_versions|array of strings|Git commit branches, tags, or hashes to exclude when deciding whether to re-use a past job.|query|@["8f03c71","8f03c71"]@ +@["badtag1","badtag2"]@| +|find_or_create |boolean |Before creating, look for an existing job that has identical script, script_version, and script_parameters to those in the present job, has nondeterministic=false, and did not fail (it could be queued, running, or completed). If such a job exists, respond with the existing job instead of submitting a new one.|query|@false@| + +When a job is submitted to the queue using the **create** method, the @script_version@ attribute is updated to a full 40-character Git commit hash based on the current content of the specified repository. If @script_version@ cannot be resolved, the job submission is rejected. -When a job is executed, the 'script_version' field is resolved to an exact Git revision and the Git hash for that revision is recorded in 'script_version'. If 'script_version' can't be resolved, the job submission will be rejected. +fn1. See the "note about specifying Git commits on the Job resource page":{{site.baseurl}}/api/schema/Job.html#script_version for more detail. h3. Reusing jobs @@ -42,21 +46,22 @@ Because Arvados records the exact version of the script, input parameters, and r notextile.
{ @@ -67,11 +72,12 @@ Run the script "crunch_scripts/hash.py" in the repository "you" using the "maste "script_parameters": { "input": "c1bad4b39ca5a924e481008009d94e32+210" } - } + }, + "find_or_create": true }
{ @@ -82,11 +88,12 @@ Run using exactly the version "d00220fb38d4b85ca8fc28a8151702a2b9d1dec5". Arvado "script_parameters": { "input": "c1bad4b39ca5a924e481008009d94e32+210" } - } + }, + "find_or_create": true }
{ @@ -99,11 +106,12 @@ Arvados is allowed to re-use a previous job if the "script_version" of the past } }, "minimum_script_version": "earlier_version_tag", - "exclude_script_versions": ["blacklisted_version_tag"] + "exclude_script_versions": ["blacklisted_version_tag"], + "find_or_create": true }
{ @@ -129,16 +137,6 @@ table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | {background:#ccffcc}.|uuid|string|The UUID of the Job in question.|path|| -h2. destroy - -destroy jobs - -Arguments: - -table(table table-bordered table-condensed). -|_. Argument |_. Type |_. Description |_. Location |_. Example | -{background:#ccffcc}.|uuid|string||path|| - h2. get Gets a Job's metadata by UUID. @@ -149,17 +147,6 @@ table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | {background:#ccffcc}.|uuid|string|The UUID of the Job in question.|path|| -h2. index - -index jobs - -Arguments: - -table(table table-bordered table-condensed). -|_. Argument |_. Type |_. Description |_. Location |_. Example | -|order|string||query|| -|where|object||query|| - h2. list List jobs. @@ -170,9 +157,7 @@ table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | |limit|integer (default 100)|Maximum number of jobs to return.|query|| |order|string|Order in which to return matching jobs.|query|| -|pageToken|string|Page token.|query|| -|q|string|Query string for searching jobs.|query|| -|where|object|Conditions for filtering jobs.|query|| +|filters|array|Conditions for filtering jobs.|query|| h2. log_tail_follow @@ -187,24 +172,16 @@ table(table table-bordered table-condensed). h2. queue -queue jobs +Get the current job queue. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | |order|string||query|| -|where|object||query|| +|filters|array||query|| -h2. show - -show jobs - -Arguments: - -table(table table-bordered table-condensed). -|_. Argument |_. Type |_. Description |_. Location |_. Example | -{background:#ccffcc}.|uuid|string||path|| +This method is equivalent to the "list method":#list, except that the results are restricted to queued jobs (i.e., jobs that have not yet been started or cancelled) and order defaults to queue priority. h2. update