Share via


List Jobs

 

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:

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

Lists all active jobs (those where the state is not Completed):

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

Lists the first ten jobs:

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

Lists all jobs, requiring JSON format with no metadata:

https://management.core.windows.net/afb1a4eb-bc88-4ce1-b1af-dfec80067464/services/importexport/storageaccounts/prodvideoacct/jobs?$format=application/json;odata=nometadata

Lists all active export jobs:

https://management.core.windows.net/afb1a4eb-bc88-4ce1-b1af-dfec80067464/services/importexport/storageaccounts/prodvideoacct/jobs?type=export\&states=Creating,Shipping,Transferring,Packaging

Lists all completed import jobs created between September 1st and October 1st 2013:

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

See Also

Azure Import/Export Service Operations