1-800-833-1132 : 1-303-449-6400


Spectra BlackPearl Converged Storage System : Spectra S3 Bucket, Object, and Job Operations : Job Operations : Stage Objects

Stage Objects
Description
Create a job to stage objects into the cache.
*
Requests
Syntax
PUT http[s]://{datapathDNSname}/_rest_/bucket/{bucket UUID or name}?operation=START_BULK_STAGE[&name={string}]​[&priority=URGENT|HIGH|NORMAL|LOW]
Request Parameters
The priority for processing this job. The job priority determines the assigned resources and processing order. Jobs with Priority URGENT can use up all of the resources and prevent other jobs from making progress. Use this priority sparingly.
Values: URGENT, HIGH, NORMAL, LOW
Default: Configured in the data policy for the bucket.
Request Elements
An XML payload, formatted as follows, must be sent to describe the staging job to create:
<Objects
   <Object Name="{
string}" Length="{64‑bit integer}"
      Offset="{64‑bit integer}" Version_Id="{string}"/>
   ...
</Objects>
where the parameters are defined as follows:
Responses
Response Elements
<MasterObjectList
   Aggregating="TRUE|FALSE"
   BucketName="{
string}"
   CachedSizeInBytes="{64‑bit integer}"
   ChunkClientProcessingOrderGuarantee="IN_ORDER|NONE"
   CompletedSizeInBytes="{64‑bit integer}"
   EntirelyInCache="TRUE|FALSE"
   JobId="{string}"
   Naked="TRUE|FALSE"
   Name="{string}"
   OriginalSizeInBytes="{64‑bit integer}"
   Priority="CRITICAL|URGENT|HIGH|NORMAL|LOW|BACKGROUND"
   RequestType="GET"
   StartDate="YYYY-MM-DDThh:mm:ss.xxxZ"
   Status="IN_PROGRESS|COMPLETED|CANCELED"
   UserId="{string}"
   UserName="{string}">
   <Nodes>
      <Node EndPoint="{
string}" Id="{string}"/>
   </Nodes>
   <Objects
      ChunkId="{
string}"
      ChunkNumber="{32‑bit integer}">
      <Object Id="{string}" InCache="TRUE|FALSE"
         Latest="TRUE|FALSE" Length="{64‑bit integer}"
         Name="{string} "Offset="{64‑bit integer}"
         VersionId="{string}"/>
      ...
   </Objects>
   ...
</MasterObjectList>
where the response elements are defined as follows:
Whether the job can have additional PUTs or GETs appended to it. Jobs aggregate if created with the aggregating request parameter set to TRUE, or if created by the BlackPearl system in response to Amazon S3 PUT and GET requests. Values: TRUE, FALSE
The amount of data that has been transferred to the cache for this job. For RequestType=GET, this is the amount of data either in cache originally, or loaded into cache from the permanent data store.
The amount of data that is completely processed for this job. For RequestType=GET, this indicates the amount of data that has been read successfully by the client.
Whether the job was created as the result of a native S3 command (TRUE) or a Create Bulk GET/PUT/VERIFY job command (FALSE). Values: TRUE, FALSE
§
IN_PROGRESS — The job is currently running.
§
COMPLETED — The job completed.
§
CANCELED — The job was canceled by the user or automatically due to internal timeouts.
Example
Error Response
If one or more objects requested only exist on tapes outside of the library, then the following response is provided:
<Error>
   <Code>CONFLICT</Code>
   <HttpErrorCode>409</HttpErrorCode>
   <Message>
     RPC DataPlanner.createGetJob&lt;60821823&gt; FAILED:
     Some of the data requested is offline (e.g. ejected, offline,
     or quiesced) and must first be brought online. Online:
     [TEST079L7]
   </Message>
   <Resource>/_rest_/bucket/eject</Resource>
   <ResourceId>40727470</ResourceId>
</Error>
Import and online the tape with the requested barcode. In the example above, the required tape is TEST079L7.
Example
Sample Request
This request creates a staging job for one object in the bucket “bucket1”.
PUT http://blackpearl-hostname/_rest_/bucket/bucket1?operation=start_bulk_stage&name="StageJob" HTTP/1.1
<Objects
   <Object Name="o1" Length="10" Offset="10" Version_Id="1"/>
   ...
</Objects>
Sample Response
HTTP/1.1 200 OK
<MasterObjectList
   Aggregating="FALSE"
   BucketName="bucket1"
   CachedSizeInBytes="0"
   ChunkClientProcessingOrderGuarantee="IN_ORDER"
   CompletedSizeInBytes="0"
   EntirelyInCache="FALSE"
   JobId="78dba377-a02a-4c15-b2a1-412514342f17"
   Naked="FALSE"
   Name="StageJob"
   OriginalSizeInBytes="0"
   Priority="NORMAL"
   RequestType="STAGE"
   StartDate="2018-1-07T22:33:17.000Z"
   Status="IN_PROGRESS"
   UserId="a6a04b3d-960a-4799-9c88-6801f5cf5449"
   UserName="user_name">
   <Nodes>
      <Node EndPoint="blackpearl-hostname"
      Id="aed40ca0-5289-49ca-9cd9-cf5a7559a1db"/>
   </Nodes>
   <Objects
      ChunkId="a909e72e-a96a-4c3e-95a3-f3472e14ae17"
      ChunkNumber="1">
      <Object Id="2ee4f397-c169-4a59-96cc-a07280412f43"
         InCache="FALSE" Latest="TRUE" Length="10"
         Name="o1" Offset="10" Version=1"/>
   </Objects>
</MasterObjectList>