List Jobs

Article
09/22/2015

The List Jobs operation lists active and completed jobs for a storage account in a subscription.

Request

The List Jobs request may be constructed as follows. HTTPS is required. Replace <subscription-id> with your subscription ID , and <storage-account-name> with the name of your storage account:

Method	Request URI
GET	https://management.core.windows.net/subscription-id/services/importexport/storageaccounts/storage-account-name/jobs[?type=type&from=from&to=to&states=states][&$skiptoken=skiptoken][&$top=top][&$format=format]

URI Parameters

The following additional parameters may be specified on the request URI.

Parameter	Description
type	Optional. Specifies that only jobs of the specified type should be returned. Value may be import or export.
from	Optional. Specifies that only jobs created at the specified time or later should be returned. Value must be a DateTime value specified in UTC format; see Formatting DateTime Property Values for details.
to	Optional. Specifies that only jobs created at the specified time or earlier should be returned. Value must be a DateTime value specified in UTC format; see Formatting DateTime Property Values for details.
states	Optional. Specifies that only jobs whose state matches the specified value should be returned. Valid values are Creating, Shipping, Transferring, Packaging, and Completed. Values are case-sensitive. To specify multiple states, separate values with a comma, without spaces.
skiptoken	Optional. A string value that identifies the portion of the results to be returned with the next list operation. Very rarely, a List Jobs operation may not return the complete set of results because there are too many jobs. In this case, a URI that includes a $skiptoken query parameter will be returned in the odata.nextlink property in the response. This URI can then be used in a subsequent call to request the next set of the results. The $skiptoken query parameter is opaque to the client.
top	Optional. An integer value that specifies how many jobs should be returned.
format	Optional. Can be used to override the Accept request header. See the Accept header for additional information. The following is an example of the $format query parameter: $format=application/json;odata=minimalmetadata

Request Headers

Request Header	Description
Accept	Optional. If specified, it must be application/json (which specifies the JSON Light format). Other values will result in response code 406 (Not Acceptable). One of the following parameters can also be included: odata=minimalmetadata odata=nometatadata odata=fullmetadata The default parameter is odata=minimalmetadata. The following is an example header: Accept: application/json;odata=minimalmetadata
Accept-Language	Optional. Currently only the values en and en-us are supported.
x-ms-date	Optional. If specified, the value should specify the date and time when the request is sent, in the RFC 1123 format.
x-ms-version	Required. Specifies the service management version to use for this request. The value of this header must be set to 2014-05-01 or 2014-11-01.

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).

Response Headers

The response for this operation includes the following headers.

Response Header	Description
Content-Encoding	The value of this header will always be identity.
Content-Length	The length of the content returned in the response. If the response body is chunked, this header is not included.
Content-Type	Specifies the format in which the results are returned. The value of this header will always be application/json.
Date	A UTC date/time value generated by the service that indicates the time at which the response was initiated.
x-ms-request-id	A value that uniquely identifies a request made against the Import/Export service.
x-ms-version	Indicates the version of the Import/Export service used to execute the request.

Response Body

The format of the response body is as follows:

{
"odata.metadata":"https://management.core.windows.net/subid/services/importexport/$metadata#Microsoft.Cis.Services.ImportExport.Public.ImportExportData.Jobs",
  "odata.count":"result-count",
  "value":[
    {
      "odata.id":"name",
      "odata.editLink":"https://management.core.windows.net/<subscription-id>/services/importexport/jobs/name",
      "Name":"name",
      "Properties":{
        "Location": "location-name",
        "Type":"job-type",
        "FriendlyName":"human-readable-job-name",
        "Description":"job-description",
    "Metadata":"job-metadata",
    "State":"job-state",
    "CancelRequested":cancel-requested,
    "PercentComplete":percent-complete,
        "ReturnAddress":{
          "Name":"return-name",
          "Address":"return-address",
          "Phone":"return-phone",
          "Email":"return-email"
        },
    "ShippingInformation":{
      "Name":"recipient-name",
      "Address":"datacenter-address"
    },
    "DeliveryPackage":{
      "CarrierName":"carrier-name",
      "TrackingNumber":"tracking-number",
      "DriveCount":drive-count,
      "ShipDate":"ship-date"
    },
    "ReturnPackage":{
      "CarrierName":"carrier-name",
      "TrackingNumber":"tracking-number",
      "DriveCount":drive-count,
      "ShipDate":"ship-date"
    },
        "ImportExportStatesPath":"importexport-states-path",
        "EnableVerboseLog":enable-verbose-log,
        "BackupDriveManifest":backup-drive-manifest,
        "IncompleteBlobListUri":incomplete-bloblist-uri
      }
},
. . .
  ],
  "odata.nextlink":"next-link"
}

The following table describes the elements of the response body.

Element	Type	Description
result-count	Integer	The number of jobs returned in the response.
Name	String	The name of a job.
Properties	property	A list of properties for the job.
Location	String	The location where this job is being processed. Note this may not be the same location of the job's storage account.
Type	String	The type of job: import or export.
FriendlyName	String	A human-readable name for the job. May contain Unicode characters, spaces, and so forth.
Description	CDATA	A human-readable description of the job. The description may be up to 1024 characters.
Metadata	CDATA	Metadata associated with the job. The metadata may be up to 1024 characters.
State	String	Current state of the job. For detailed information about job states, see Retrieving State Information for a Job.
CancelRequested	Boolean	Indicates whether a request has been submitted to cancel the job.
PercentComplete	Integer	Overall percentage completed for the job in terms of bytes uploaded or downloaded versus total bytes.
ReturnAddress	property	Specifies the return address information for the job.
Name	String	Name of the recipient who will receive the import or export drives when they are returned.
Address	String	Address of the recipient of the returned drives.
Phone	String	Phone number of the recipient of the returned drives.
Email	String	Email address of the recipient of the returned drives.
ShippingInformation	property	Contains information about the Windows Azure region to which the drives should be shipped.
ShippingInformation/Name	String	The name of the recipient at the data center.
ShippingInformation/Address	String	The address of the data center.
DeliveryPackage	property	Contains information about the package being shipped by the customer to the Microsoft data center.
CarrierName	String	The name of the carrier that is used to ship the import or export drives.
TrackingNumber	String	The tracking number of the package.
DriveCount	Integer	The number of drives included in the package.
ShipDate	Date	The date when the package is shipped.
ReturnPackage	property	Contains information about the package being shipped from the Microsoft data center to the customer to return the drives. The format is the same as the DeliveryPackage property above. This property is not included if the drives have not yet been returned.
ImportExportStatesPath	String	The container or virtual directory to which the copy logs and backups of drive manifest files (if enabled) will be stored. If the job specifies a storage account key for authentication, then this path will refer to a container name. If the job specifies a container SAS (shared access signature), then this path will refer to a virtual directory beneath the container named in the shared access signature. See Import/Export Service Log File Format for details. Note that in REST version 2014-05-01, this element is called ImportExportStatesContainer and its value must be a container name.
EnableVerboseLog	Boolean	See detailed description in the Put Job operation.
BackupDriveManifest	Boolean	See detailed description in the Put Job operation.
IncompleteBlobListUri	String	A blob path that points to a block blob containing a list of blob names that were not exported due to insufficient drive space. If all blobs were exported successfully, then this element is not included in the response. Applies only to export jobs. The blob containing the list is stored in the container specified by the ImportExportStatesPath element, using the following naming convention: waies/jobname_timestamp_incomplete-blobs.xml.
State	String	The drive's current state. See Retrieving State Information for a Job for detailed information about drive states.
PercentComplete	Integer	Percentage completed for the drive. This value is applicable only in the Transferring and Completed drive states.
VerboseLogUri	String	A URI that points to the blob containing the verbose log for the data transfer operation. The blob will be stored in the container specified in the ImportExportStatesPath element. This element is included in the response only if verbose logging has been enabled.
ErrorLogUri	String	A URI that points to the blob containing the error log for the data transfer operation. The blob will be stored in the container specified in the ImportExportStatesPath element.
ManifestUri	String	A URI that points to the blob containing the drive manifest file. This property is included in the response only if the BackupDriveManifest property has been set to true by a Put Job or Update Job Properties request.
next-link	String	Included in the response when there are additional results to be retrieved. A URI that can be used to request the remaining results from the service.

If the request fails, the response body will contain the following error message:

{
  "odata.error": {
    "code": "http-code",
    "message": {
        "lang": "en-US",
        "value": "detailed-error-message"
    },
    "azure.values": [
      { "ExtendedCode": "extended-error-code" },
      { "ExtendedInformation": "extended-information" }
    ]
  }
}

The following table describes the elements of the error response.

Element	Type	Description
http-code	String	The standard HTTP status code returned when the request fails.
detailed-error-message	String	A human-readable description of the error.
Extended-code	String	A predefined error code, if applicable.
Extended-information	String	Additional information provided to diagnose the error.

Sample Request and Response

The following shows a sample request and response for the List Jobs operation.

Request

GET https://management.core.windows.net/0382f90a-8338-4ddf-9aae-b6154e5a7fd2/services/importexport/StorageAccounts/xtprodtestwe/jobs?timeout=3600 HTTP/1.1
x-ms-version: 2014-05-01
Content-Type: application/json
Accept: application/json
Host: management.core.windows.net
Connection: Keep-Alive

Response

HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Length: 1082
Content-Type: application/json;odata=minimalmetadata;streaming=true;charset=utf-8
Content-Encoding: identity
Content-Language: en-us
Server: 1.0.6198.70 (rd_rdfe_stable.140426-2318) Microsoft-HTTPAPI/2.0
x-ms-servedbyregion: ussouth2
DataServiceVersion: 3.0;
x-ms-version: 2014-05-01
x-ms-request-id: 20f132005176977abb4f94250e13e45c
Date: Wed, 30 Apr 2014 00:37:22 GMT

{"odata.metadata":"https:\/\/management.core.windows.net\/0382f90a-8338-4ddf-9aae-b6154e5a7fd2\/services\/importexport\/$metadata#Microsoft.Cis.Services.ImportExport.Public.ImportExportData.Jobs","odata.count":"1","value":[{"odata.id":"am2_test_20140429_export","odata.editLink":"https:\/\/management.core.windows.net\/0382f90a-8338-4ddf-9aae-b6154e5a7fd2\/services\/importexport\/jobs\/am2_test_20140429_export","Name":"am2_test_20140429_export","Properties":{"Location":"West Europe","Type":"Export","FriendlyName":"test","Description":"test job for AM2","State":"Shipping","CancelRequested":false,"ReturnAddress":{"Name":"John Doe","Address":" One Microsoft Way, Redmond, WA 98052","Phone":"1-800-000-0000","Email":"johndoe@outlook.com"},"ShippingInformation":{"Name":"Windows Azure Import Export Service","Address":"Tupolevlaan 101;;Schiphol-Rijk;;1119 PA;Netherlands (NL)"},"DeliveryPackage":{"CarrierName":"FedEx","TrackingNumber":"9999999999","DriveCount":1},"ImportExportStatesPath":"waimportexport","EnableVerboseLog":true,"BackupDriveManifest":true}}]}

Remarks

A List Jobs operation returns a maximum of 1000 jobs. If there are more than 1000 jobs that meet the criteria specified in the request, a continuation link is returned in the odata.nextlink element, which can be used in a subsequent request to retrieve the remaining results.

The following sample URIs demonstrate different ways to call the List Jobs operation.

Lists all jobs associated with a storage account named prodvideoacct:

https://management.core.windows.net/afb1a4eb-bc88-4ce1-b1af-dfec80067464/services/importexport/storageaccounts/prodvideoacct/jobs

Lists all import jobs for storage account prodvideoacct:

https://management.core.windows.net/afb1a4eb-bc88-4ce1-b1af-dfec80067464/services/importexport/storageaccounts/prodvideoacct/jobs?type=import

Lists all jobs that were created between September 1st, 2013 and May 1st, 2014:

https://management.core.windows.net/afb1a4eb-bc88-4ce1-b1af-dfec80067464/services/importexport/storageaccounts/prodvideoacct/jobs?from=2013-09-01T00:00:00.0000000Z\&to=2014-05-01T00:00:00.0000000Z

Lists all jobs that are in the Creating state:

https://management.core.windows.net/afb1a4eb-bc88-4ce1-b1af-dfec80067464/services/importexport/storageaccounts/prodvideoacct/jobs?states=Creating

Lists all jobs that are in Transferring state:

https://management.core.windows.net/afb1a4eb-bc88-4ce1-b1af-dfec80067464/services/importexport/storageaccounts/prodvideoacct/jobs?states=Transferring

Lists all jobs that have been completed: