Get Job

  • Article

 

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

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)

See Also

Azure Import/Export Service Operations