Get Job

Article
09/22/2015

The Get Job operation gets information about an existing job from the Windows Azure Import/Export service.

Request

The Get Job request may be constructed as follows. HTTPS is required. Replace <subscription-id> with your subscription ID, <storage-account-name> with the name of your storage account, and <job-name> with the name of your import job or export job:

Method	Request URI
GET\|HEAD	https://management.core.windows.net/<subscription-id>/services/importexport/storageaccounts/<storage-account-name/jobs/<job-name>[?$format=format]

URI Parameters

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

Parameter	Description
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

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

The following table describes required and optional 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.
Content-Length	Optional. If this header is specified, the value must be set to 0.
x-ms-date	Optional. If specified, the value should specify the date and time when the request is sent, in 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.
If-Modified-Since	Optional. A DateTime value. Specify this header to perform the operation only if the resource has been modified since the specified time.
If-Unmodified-Since	Optional. A DateTime value. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.
If-Match	Optional. An ETag value. Specify this header to perform the operation only if the resource's ETag matches the value specified.
If-None-Match	Optional. An ETag value, or the wildcard character (). Specify this header to perform the operation only if the resource's ETag does not match the value specified. Specify the wildcard character () to perform the operation only if the resource does not exist, and fail the operation if it does exist.

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.
ETag	Contains a value that the client can use to perform conditional operations by using the If-Match or If-None-Match request headers.
Last-Modified	The date/time that the job was last modified. The date format follows RFC 1123. For more information, see Representation of Date/Time Values in Headers.
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/@Element",
  "odata.type":"Microsoft.Cis.Services.ImportExport.Public.Job",
  "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"
    },
    "ReturnShipping":{
      "CarrierName":"carrier-name",
      "CarrierAccountNumber":"carrier-account-number"
    },
"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
  },
  "DriveList":[
    {
      "DriveId":"drive-id",
      "BitLockerKey":"bitlocker-key",
      "ManifestFile":"manifest-file-path",
      "ManifestHash":"manifest-hash-value",
      "State":"drive-state",
      "CopyStatus":" copy-status",
      "PercentComplete":percent-complete,
      "VerboseLogUri":"verbose-log-uri",
      "ErrorLogUri":"error-log-uri",
      "ManifestUri":"manifest-uri"
    },
    {
      . . .
    },
    . . .
    ]
  }
  "Export":{
    Blob-selection-fragment
  }
}

Blob-selection-fragment ::=
Blob-list-fragment | Blob-list-blob-fragmentBlob-list-fragment ::=
"BlobList":{
  "BlobPath":[
    "blob-path",
    "blob-path",
    . . .
  ],
  "BlobPathPrefix":[
    "blob-prefix",
    "blob-prefix",
    . . .
  ]
}

Blob-list-blob-fragment ::=
    "BlobListBlobPath":"blob-list-blob-path"

The following table describes the elements of the response body.

Element	Type	Description
Name	String	The name of the import or export job.
Properties	property	A list of properties for the job.
Location	String	The location where this job is being processed. Note this may be different than the location of the storage account associated with the job.
Type	String	The type of job: import or export.
FriendlyName	String	Human-readable name for the job. May contain Unicode characters, spaces, and so forth.
Description	CDATA	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 descriptions of 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.
ReturnShipping	Property	Optional. Specifies the return carrier and customer’s account with the carrier.
CarrierName	String	Required. The carrier’s name.
CarrierAccountNumber	String	Required. The customer’s account number with the carrier.
ShippingInformation	property	Contains information about the Windows Azure datacenter to which the drives should be shipped.
ShippingInformation/Name	String	The name of the recipient at the datacenter.
ShippingInformation/Address	String	The address of the datacenter.
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 Put Job for a detailed description.
BackupDriveManifest	Boolean	See Put Job for a detailed description.
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.
DriveList	property	Contains information about a set of drives. This element is not included in the response if there are no drives associated with the job, for example, if the job is a newly created export job for which the drives have not yet been received.
Drive	property	Contains information about a drive.
DriveId	String	The drive's hardware serial number, stripped of spaces.
BitLockerKey	String	The BitLocker key used to encrypt the drive. For export drives, this field is only returned when the drive has been shipped back.
ManifestFile	String	The relative path of the manifest file on the drive. The relative path is a fully qualified DOS path, without the drive letter.
ManifestHash	String	The Base16-encoded MD5 hash of the manifest file on the drive.
State	String	The drive's current state. See Retrieving State Information for a Job for detailed information about drive states.
CopyStatus	String	Detailed status about the data transfer process. This field is not returned in the response until the drive is in the Transferring state. The value of this field can be one of the below: None InProgress Completed CompletedWithWarnings CompletedWithErrors InternalError ManifestCorrupted ManifestNameInvalid ManifestNameTooLong ManifestNotFound ManifestAccessDenied ManifestFormatInvalid ReadManifestFailed ManifestDriveIdMismatch BlobListFormatInvalid DiskNotFound VolumeNotNtfs DiskOperationFailed BitLockerNotActivated BitLockerProtectorNotFound BitLockerKeyInvalid BitLockerUnlockVolumeFailed BitLockerFailed
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.
Export	property	A property containing information about the blobs to be exported for an export job. This property is included for export jobs only.
BlobList	property	The list of the blobs to be exported.
BlobPath	String	The relative URI to the blob, beginning with the container name. If the blob is in root container, the container is designated as $root.
BlobPathPrefix	String	A blob path prefix that selects all blobs whose relative path begins with the prefix. Note that the prefix always starts with a forward slash "/", followed by the container name. If the container is the root container, $root must be explicitly included.
BlobListBlobPath	String	The relative URI to the blob that contains the list of blob paths or blob path prefixes as defined in the Put Job operation, beginning with the container name. If the blob is in root container, $root must be explicitly included.

If the request fails, the response body contains 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" }
    ]
  }
}

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 Get Job operation.

Request

GET https://management.core.windows.net/afb1a4eb-bc88-4ce1-b1af-dfec80067464/services/importexport/storageaccounts/xttest/jobs/MySampleJob?timeout=3600 HTTP/1.1
x-ms-version: 2014-05-01
x-ms-date: Wed, 30 Apr 2014 00:29:36 GMT
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: 1554
Content-Type: application/json;odata=minimalmetadata;streaming=true;charset=utf-8
Content-Encoding: identity
Content-Language: en-us
Last-Modified: Wed, 30 Apr 2014 00:25:42 GMT
ETag: W/"datetime'2014-04-30T00%3A25%3A42.3131245Z'"
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: 7f1ce9a13cba9f58b6deaa73690e8055
Date: Wed, 30 Apr 2014 00:29:36 GMT

{"odata.metadata":"https:\/\/management.core.windows.net\/afb1a4eb-bc88-4ce1-b1af-dfec80067464\/services\/importexport\/$metadata#Microsoft.Cis.Services.ImportExport.Public.ImportExportData.Jobs\/@Element","odata.id":"MySampleJob","odata.editLink":"https:\/\/management.core.windows.net\/afb1a4eb-bc88-4ce1-b1af-dfec80067464\/services\/importexport\/jobs\/MySampleJob","Name":"MySampleJob","Properties":{"Location":"South Central US","Type":"Import","FriendlyName":"A sample job using Windows Azure Import\/Export service.","Description":"Optional more detailed description about this job.","State":"Creating","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":"1111 First Ave;;Any City;WA;98999;USA"},"DeliveryPackage":{"CarrierName":"FedEx","TrackingNumber":"999999999999","DriveCount":2,"ShipDate":"4\/30\/2014 12:25:40 AM"},"ImportExportStatesPath":"waimportexport","EnableVerboseLog":true,"BackupDriveManifest":true},"DriveList":[{"DriveId":"1W0F9LV1","BitLockerKey":"259358-100188-581471-154165-090552-296406-410091-426844","ManifestFile":"\\DriveManifest.xml","ManifestHash":"B306C4B34DAA0E99957A4B9C779D2FA2","State":"Specified"},{"DriveId":"9WM3NZFS","BitLockerKey":"360294-634645-210485-401192-415272-513568-389334-516043","ManifestFile":"\\DriveManifest.xml","ManifestHash":"DDBEDA902DABD438D2C40B2744C64B1D","State":"Specified"}]}

Remarks

The Get Job operation returns the overall status of a job, including the status of the job and of each drive comprising the job.

All properties noted as optional in the request body of the Put Job operation will be returned by the Get Job operation only if they have been specified as part of the Put Job request.

The response for the Get Job operation includes basic information such as job name, storage account name, type, description, and job state. In addition, depending on the type and state of the job, the response may also include other information, such as shipping and return information for drives and BitLocker keys for export jobs.

The verbose log is a blob that contains the complete copy log for a drive. It can be used to determine the copy status of each file on a drive and to view any warnings or errors that were logged during the copy operation. See Import/Export Service Log File Format for its format.

By default, the verbose log is not generated. To enable it, set EnableVerboseLog to true in a call to Put Job or Update Job Properties.

The error log is a subset of the verbose log. It contains only warning and error entries. The error log is always enabled.

Both the error logs and verbose logs (if enabled) are stored in the container specified by the ImportExportStatesPath element. If no container is specified, the logs are stored in a default container named waimportexport. Logs are stored as block blobs with the following naming convention: waies/jobname_driveid_timestamp_logtype.xml.

You can specify conditional headers to retrieve a job only when certain conditions are met. When specifying conditional headers, keep in mind the following:

If a request specifies both the If-None-Match and If-Modified-Since headers, the request is evaluated based on the criteria specified in If-None-Match.
If a request specifies both the If-Match and If-Unmodified-Since headers, the request is evaluated based on the criteria specified in If-Match.
With the exception of the two combinations of conditional headers listed above, a request may specify only a single conditional header. Specifying more than one conditional header results in status code 400 (Bad Request).

The following table indicates the response codes returned for an unmet condition for each conditional header:

Conditional header	Response code if condition has not been met
If-Modified-Since	Precondition Failed (412)
If-Unmodified-Since	Precondition Failed (412)
If-Match	Precondition Failed (412)
If-None-Match	Precondition Failed (412)

Share via

Get Job

Request

URI Parameters

Request Headers

Request Body

Response

Status Code

Response Headers

Response Body

Sample Request and Response

Request

Response

Remarks

See Also

Additional resources