Get Job List

Gets the values of the specified properties for all jobs for the HPC cluster, or optionally for jobs filtered by job owner or job state.

Request

You can specify the Get Job List request as follows.

MethodRequest URI
GET (before HPC Pack 2016)https://head_node_name:port/WindowsHPC/HPC_cluster_name/Jobs
GET (HPC Pack 2016)https://head_node_name:port/WindowsHPC/Jobs

 

For instances of the REST web service that are hosted in Azure, the head node name should have a format of Windows_Azure_service_name.cloudapp.net.

To get the name to use for an HPC cluster that runs at least Microsoft HPC Pack 2008 R2 with Service Pack 3 (SP3), use the Get Clusters operation.

URI Parameters

You can specify the following additional parameters on the request URI.

ParameterDescription
Properties

Optional. A comma-separated list of the names for the properties of the jobs for which you want to get values. For a list of properties for which you can get values, see the Remarks section.

If you do not specify the Properties parameter, the response contains values for the Id, Owner, Name, State, and Priority properties of the jobs.

If a property with a specified name does not exist for a job, an error occurs.

Owner

Optional. The user who created, submitted, or queued the job.

QueryId

Specifies internal data from the x-ms-continuation-QueryId header from the response in the previous Get Job List operation in a set of Get Job List operations. For more information, see the Response Headers section later in this topic.

CurrentObjectNumber

Specifies internal data from the x-ms-continuation-CurrentObjectNumber header from the response in the previous Get Job List operation in a continuation sequence of Get Job List operations. For more information, see the Response Headers section later in this topic. Deprecated starting with Microsoft HPC Pack 2008 R2 with Service Pack 3 (SP3).

api-version

Optional. Specifies the version of the operation to use for this request. To specify Microsoft HPC Pack 2008 R2 with Service Pack 3 (SP3), use a value of 2011-11-01. The minimum version that supports this URI parameter is Microsoft HPC Pack 2008 R2 with SP3.

The value of this URI parameter is ignored if the request also contains the api-version header.

$filter

Optional. Specifies OData filters to use for this request in the following format "$filter=<filter1>%20and%20<filter2>…".

To filter the jobs by a valid job state, use the filter "JobState%20eq%20<JobState>". To retrieve jobs whose state changed after a certain date and time, use the filter "ChangeTimeFrom%20eq%20<DateTime>".

A null value is ignored.

The minimum version that supports this URI parameter is Microsoft HPC Pack 2012. To use this parameter, also specify the Render URI parameter set to RestPropRender and a minimum api-version value of 2012-11-01.

Example: "$filter=JobState%20eq%20queued%20and%20 ChangeTimeFrom%20eq%202015-10-16&Render=RestPropRender&api-version=2012-11-01". For information about job states, see JobState.
RenderRequired if the $filter URI parameter is specified. Set the value to RestPropRender to specify that the response body is formatted in XML compatible with Microsoft HPC Pack 2008 R2 with Service Pack 2 (SP2). The minimum version that supports this URI parameter is Microsoft HPC Pack 2012.
SortJobsByOptional. A job property by which jobs will be sorted. If this parameter is not specified or a property with a specified name does not exist for a job, the result will be sorted by job Id.
RowsPerReadOptional. Specifies how many lines of data to retrieve each time. The default is set to 10. At least one record will be retrieved.

 

Request Headers

The following table describes required and optional request headers.

Request HeaderDescription
api-version

Optional. Specifies the version of the operation to use for this request. To specify Microsoft HPC Pack 2008 R2 with SP3, use a value of 2011-11-01. The minimum version that supports this header is Microsoft HPC Pack 2008 R2 with SP3.

The value specified in this header overrides the value specified in the api-version URI parameter if both are specified.

CCP_Version

Optional. Specifies the version of the operation to use for this request.

Deprecated beginning with Microsoft HPC Pack 2008 R2 with Service Pack 3 (SP3).

 

Request Body

None.

Response

The response includes an HTTP status code, a set of response headers, and a response body in XML format.

Status Code

A successful operation returns status code 200 (OK). For more information about status codes, see HttpStatusCode.

The error response is dependent upon the api-version used in the request. If the api-version is not provided, or CCP_Version is specified, then the error response will be an XML string (Note: The error message will vary based on the error):


<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">Error message text.</string>


If the api-version is 2011-11-01 or later, the error message will be a more descriptive XML response (Note: Values will vary based on the error):


<HpcWebServiceFault xmlns="http://schemas.microsoft.com/HPCS2008R2/common" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Code>267386880</Code>
  <Message>Error message text.</Message>
  <Values i:nil="true" xmlns:a="http://schemas.datacontract.org/2004/07/System.Collections.Generic"/>
</HpcWebServiceFault>

Response Headers

The response for this operation includes the following headers.

Response HeaderDescription
x-ms-hpc-authoritychain

A comma-separated list of RFC 1918 IP addresses that indicate the sequence of instances of the REST web service that the operation called in order from to right.

Only responses from instances of the REST web service that are hosted on Azure contain this header. Responses from instances of the REST web service that are hosted on premise omit this header.

This header is supported beginning with Microsoft HPC Pack 2008 R2 with SP3 and is not available in previous versions.

x-ms-continuation-queryId

Enables large sets of data to be returned in smaller responses across a continuation sequence of several requests. The value of this header is to be assigned to the queryId query string parameter in the next call in the sequence of calls to the Get Job List operation. The response to the Get Job List operation contains this header as long as additional data remains to be processed. You use the values of this header for one operation in the queryId URI parameter for the next operation.

The format of these data in this header is not guaranteed to remain unchanged. You should only copy the data in this header from one operation in a set of multiple operations to the queryId URI parameter for the next operation. You should not use the data in this header or depend on the format of the data in this header in any other way.

For an example of how to use this header and URI parameter in a way that potential changes will not impact, see the code for the sample client applications for REST API. For information about how to get these sample client applications, see Getting Sample Programs that use the REST API.

x-ms-continuation-CurrentObjectNumber

Contains internal data that support working with sets of data that are too large or too expensive to get in a single response body by dividing the Get Job List operation into a set of multiple Get Job List operations. The response to the Get Job List operation contains this header as long as additional data remains to be processed. You use the values of this header for one operation in the CurrentObjectNumber URI parameter for the next operation.

The format of the data in this header is not guaranteed to remain unchanged. You should only copy the data in this header from one operation in a set of multiple operations to the CurrentObjectNumber URI parameter for the next operation. You should not use the data in this header or depend on the format of the data in this header in any other way.

For an example of how to use this header and URI parameter in a way that potential changes will not impact, see the code for the sample client applications for REST API.

Deprecated starting with Microsoft HPC Pack 2008 R2 with SP3.

 

The response for this operation also includes standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response Body

The format of the response body is as follows.


<ArrayOfObject xmlns="http://schemas.microsoft.com/HPCS2008R2/common" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Object>
        <Properties>
            <Property>
                <Name>job1_property1_name</Name>
                <Value>job1_property1_value</Value>
           </Property>
           <Property>
               <Name>job1_property2_name</Name>
               <Value>job1_property2_value</Value>
           </Property>
           ...
        </Properties>
    </Object>
        <Properties>
            <Property>
                <Name>job2_property1_name</Name>
                <Value>job2_property1_value</Value>
           </Property>
           <Property>
               <Name>job2_property2_name</Name>
               <Value>job2_property2_value</Value>
           </Property>
           ...
        </Properties>
    </Object>
    ...
</ArrayOfObject>

The following table describes each of the elements in the response XML.

ElementDescription
ArrayOfObject

Represents the set of jobs with the specified owner, or all jobs if no owner is specified.

Object

Represents a single job.

Properties

Represents the set of properties for the job.

Property

Represents a single property for the job.

Name

Contains the name of the property.

Value

Contains the value of the property.

 

Remarks

The following table shows the job properties for which you can get the values or by which you can sort results. For information about the property, see the corresponding property of the ISchedulerJob interface in the managed API for Microsoft HPC Pack.

PropertyCorresponding ISchedulerJob Property
IdISchedulerJob.Id
NameISchedulerJob.Name
OwnerISchedulerJob.Owner
UserNameISchedulerJob.UserName
ProjectISchedulerJob.Project
RuntimeSecondsISchedulerJob.Runtime
SubmitTimeISchedulerJob.SubmitTime
CreateTimeISchedulerJob.CreateTime
EndTimeISchedulerJob.EndTime
StartTimeISchedulerJob.StartTime
ChangeTimeISchedulerJob.ChangeTime
StateISchedulerJob.State
PreviousStateISchedulerJob.PreviousState
MinCoresISchedulerJob.MinimumNumberOfCores
MaxCoresISchedulerJob.MaximumNumberOfCores
MinNodesISchedulerJob.MinimumNumberOfNodes
MaxNodesISchedulerJob.MaximumNumberOfNodes
MinSocketsISchedulerJob.MinimumNumberOfSockets
MaxSocketsISchedulerJob.MaximumNumberOfSockets
UnitTypeISchedulerJob.UnitType
RequestedNodesISchedulerJob.RequestedNodes
IsExclusiveISchedulerJob.IsExclusive
RunUntilCanceledISchedulerJob.RunUntilCanceled
NodeGroupsISchedulerJob.NodeGroups
FailOnTaskFailureISchedulerJob.FailOnTaskFailure
AutoCalculateMaxISchedulerJob.AutoCalculateMax
AutoCalculateMinISchedulerJob.AutoCalculateMin
CanGrowISchedulerJob.CanGrow
CanShrinkISchedulerJob.CanShrink
PreemptableISchedulerJob.CanPreempt
ErrorMessageISchedulerJob.ErrorMessage
HasRuntimeISchedulerJob.HasRuntime
RequeueCountISchedulerJob.RequeueCount
MinMemoryISchedulerJob.MinMemory
MaxMemoryISchedulerJob.MaxMemory
MinCoresPerNodeISchedulerJob.MinCoresPerNode
MaxCoresPerNodeISchedulerJob.MaxCoresPerNode
EndpointReferenceISchedulerJob.EndpointAddresses
SoftwareLicenseISchedulerJob.SoftwareLicense
OrderByISchedulerJob.OrderBy
ClientSourceISchedulerJob.ClientSource
ProgressISchedulerJob.Progress
ProgressMessageISchedulerJob.ProgressMessage
TargetResourceCountISchedulerJob.TargetResourceCount
ExpandedPriorityISchedulerJob.ExpandedPriority
ServiceNameISchedulerJob.ServiceName
JobTemplateISchedulerJob.JobTemplate
HoldUntilISchedulerJob.HoldUntil
NotifyOnStartISchedulerJob.NotifyOnStart
NotifyOnCompletionISchedulerJob.NotifyOnCompletion
ExcludedNodesISchedulerJob.ExcludedNodes
EmailAddressISchedulerJob.EmailAddress
PriorityISchedulerJob.Priority
AllocatedNodesISchedulerJob.AllocatedNodes
PoolISchedulerJob.Pool
JobValidExitCodesISchedulerJob.ValidExitCodes
ParentJobIdsISchedulerJob.ParentJobIds
FailDependentTasksISchedulerJob.FailDependentTasks
NodeGroupOpISchedulerJob.NodeGroupOp
SingleNodeISchedulerJob.SingleNode
ChildJobIdsISchedulerJob.ChildJobIds
EstimatedProcessMemoryISchedulerJob.EstimatedProcessMemory

 

Requirements

Product

HPC Pack 2008 R2 with at least SP2, or a later version of HPC Pack.

 

 

Show: